pip и requirements.txt: установка и фиксация зависимостей

pip устанавливает Python-дистрибутивы из индекса, локального каталога или файла и размещает их в окружении выбранного интерпретатора. Файл requirements.txt описывает набор требований, который pip должен установить. Вместе они дают воспроизводимый процесс, если команда запускается в чистом виртуальном окружении, а правила версий выбраны осознанно.

Запускайте pip через нужный Python

Команда python -m pip сначала выбирает интерпретатор, а затем запускает принадлежащий ему модуль pip. Это яснее короткой команды pip, которая может указывать на глобальную установку. Перед изменением окружения полезно проверить python -m pip --version: вывод содержит и версию pip, и каталог, откуда он загружен.

Установка по имени без ограничения версии разрешает получить новый релиз при следующем развёртывании. Точное требование package==1.2.3 выбирает одну версию, а диапазон вроде package>=1.2,<2 допускает совместимые обновления, но не гарантирует одинаковый полный граф на разные даты. Выбор зависит от того, является файл входным списком или снимком проверенного окружения.

Установка из requirements.txt

Каждая значимая строка файла задаёт требование или опцию pip. Для небольшого приложения можно начать с явного диапазона прямой зависимости:

urllib3>=2,<3

После создания и активации .venv выполните:

python -m pip install -r requirements.txt
python -c "import urllib3; print(urllib3.__name__)"
python -m pip check

Ожидаются строки urllib3 и No broken requirements found.. Для установки нужен доступ к настроенному индексу или локальному источнику пакетов. Конкретную выбранную версию можно увидеть командой python -m pip show urllib3.

Фиксация и обновление

python -m pip freeze выводит установленные дистрибутивы с точными версиями в формате требований. Команда python -m pip freeze > requirements.txt удобна для снимка маленького окружения, но записывает и транзитивные зависимости, не объясняя, зачем они появились. Поэтому снимок следует строить только в чистой .venv, а прямые зависимости хранить осмысленно или применять специализированный процесс генерации lock-файла.

Обновление — отдельное изменение проекта. Сначала меняют выбранное ограничение, затем создают чистое окружение, устанавливают весь файл и запускают тесты. Флаг --upgrade не заменяет проверку совместимости: он просит pip рассмотреть более новые подходящие версии, но не знает бизнес-контракты приложения.

Как разбирать сбои установки зависимостей

Ошибка Could not open requirements file обычно означает неверный текущий каталог или имя файла. Проверьте pwd, список файлов и передайте существующий путь после -r. Если установка завершилась, а импорт не работает, сопоставьте пути из sys.executable и python -m pip --version. При сообщении resolver о несовместимых ограничениях прочитайте, какие два требования требуют разные диапазоны одной зависимости; не обходите конфликт случайным понижением пакета. После любых ручных изменений выполните python -m pip check, чтобы найти уже установленный несовместимый граф.

Воспроизводим окружение из двух файлов

В новом окружении создайте файл с одной прямой зависимостью и допустимым диапазоном, установите его и сохраните вывод pip freeze в отдельный requirements.lock.txt. Сравните файлы: отметьте прямое требование и автоматически добавленные зависимости. Затем создайте вторую чистую .venv, установите снимок и запустите тот же импорт. Самостоятельная проверка успешна, если pip check проходит в обоих окружениях, а pip freeze второго совпадает со снимком с учётом платформенных различий.

Правила надёжной фиксации версий

• Флаг -r означает чтение требований из файла, а не установку пакета с таким именем.
• Диапазон версий выражает допустимость, точная фиксация — выбранный результат разрешения.
• Снимок нужно получать из чистого окружения, иначе в него попадут чужие пакеты.
• После установки проверяйте импорт, тесты и python -m pip check.

Вопросы о requirements и pip

requirements.txt обязан называться именно так?

Нет. Это распространённое соглашение. Можно иметь requirements-dev.txt и другие файлы, если команды явно передают правильный путь через -r и назначение каждого файла понятно команде.

Чем pip freeze отличается от pip list?

pip list предназначен прежде всего для просмотра окружения. pip freeze формирует строки требований, которые можно снова передать pip, поэтому его формат удобнее для снимка.

Следует ли коммитить requirements.txt?

Если проект использует этот файл как часть установки или развёртывания, его коммитят вместе с кодом. Сам каталог виртуального окружения при этом в репозиторий не помещают.