Чем lock-файл (poetry.lock, Pipfile.lock или requirements.txt, сгенерированный pip-compile) отличается от файла с верхнеуровневыми зависимостями (pyproject.toml)? Как воспроизводимость сборки связана с этими файлами?

Короткий ответ

pyproject.toml описывает желаемые, часто диапазонные версии прямых зависимостей, а lock-файл фиксирует точный, полностью разрешённый набор версий всех зависимостей, включая транзитивные, вместе с хешами — это гарантирует, что установка на любой машине даёт одинаковое окружение.

Как это работает подробнее

при добавлении зависимости resolver решает задачу совместимости версий по всему дереву и записывает результат в lock-файл; при установке по lock-файлу resolver уже не нужен — пакеты ставятся по зафиксированным версиям и хешам.

Пример кода

Пример конфигурацииКопировать

[tool.poetry.dependencies]
python = "^3.12"
fastapi = "^0.110"

Что использовать на практике

• Рекомендация. в репозиторий коммитят оба файла: pyproject.toml читают люди, lock-файл перегенерируют командой и тоже коммитят, чтобы CI и прод использовали именно его. Конфликт версий resolver обнаруживает на этапе lock.

Подводные камни

• Риск. редактировать lock-файл руками — при следующей регенерации изменения потеряются; не коммитить lock-файл, полагаясь на диапазоны в pyproject.toml — разные установки могут получить разные версии транзитивных пакетов.