Poetry: управление зависимостями Python

Poetry — это менеджер зависимостей и инструмент упаковки для Python, который хранит метаданные проекта в pyproject.toml, а точные версии пакетов — в poetry.lock. В отличие от связки pip и venv, он сам создаёт окружение, разрешает конфликты версий и умеет собирать wheel и sdist. Ниже — рабочий процесс от установки до CI, с командами, которые можно выполнять на сервере или ноутбуке.

Зачем Poetry, если есть pip и venv

pip устанавливает пакеты, но не фиксирует полное дерево зависимостей: requirements.txt с точными версиями приходится поддерживать вручную. Poetry решает три задачи: описывает зависимости декларативно, строит воспроизводимый lock-файл и изолирует проект в отдельном виртуальном окружении. Дополнительно он проверяет совместимость с версией Python и умеет публиковать пакеты.

• Декларативность. В одном файле лежат имя проекта, версия, зависимости и настройки сборки.
• Воспроизводимость. poetry.lock фиксирует не только прямые пакеты, но и транзитивные.
• Группы зависимостей. Тестовые и документационные пакеты не попадают в прод-окружение.

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

Установка и первичная настройка

Официальный установщик кладёт бинарник в ~/.local/bin. Не запускайте его от root: Poetry должен принадлежать пользователю, который работает с проектом.

curl -sSL https://install.python-poetry.org | python3 -
export PATH="$HOME/.local/bin:$PATH"
poetry --version

Альтернатива — pipx, если он уже используется для CLI-утилит. Плагин экспорта ставится отдельно, потому что команда poetry export вынесена в расширение.

pipx install poetry
pipx inject poetry poetry-plugin-export
poetry self show plugins

Полезная настройка — хранить окружение внутри каталога проекта. Тогда редакторы и линтеры находят интерпретатор без дополнительных настроек.

poetry config virtualenvs.in-project true
poetry config cache-dir
poetry config --list

Новый проект и pyproject.toml

Команда poetry new создаёт скелет пакета, а poetry init добавляет конфигурацию в существующий каталог. Современный Poetry использует таблицу [project] из PEP 621, поэтому файл остаётся понятным другим инструментам.

poetry new billing-service
cd billing-service
poetry init --python ">=3.11,<3.14"

Минимальный pyproject.toml выглядит так:

[project]
name = "billing-service"
version = "0.1.0"
description = "Сервис выставления счетов"
requires-python = ">=3.11,<3.14"
dependencies = [
    "httpx>=0.27,<1.0",
    "pydantic>=2.7,<3.0",
]

[tool.poetry.group.dev.dependencies]
pytest = "^8.2"
ruff = "^0.6"

[build-system]
requires = ["poetry-core>=2.0"]
build-backend = "poetry.core.masonry.api"

Добавление зависимостей и групп

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

poetry add "httpx>=0.27,<1.0"
poetry add --group dev pytest ruff
poetry add --group docs mkdocs-material
poetry remove httpx
poetry show --tree

Команда poetry show --tree показывает, кто именно притянул пакет. Это быстрее, чем читать lock-файл, когда нужно понять причину конфликта версий.

Lock-файл и воспроизводимая установка

poetry.lock нужно коммитить в git. На сервере и в CI устанавливайте строго по нему, иначе сборки начнут расходиться. В Poetry 2.x команда poetry lock по умолчанию не обновляет уже зафиксированные пакеты; для полного пересчёта используется --regenerate.

poetry lock
poetry install --sync
poetry install --without dev
poetry check --lock

--sync удаляет из окружения пакеты, которых нет в lock-файле. Это удобно в CI, но опасно на рабочей машине, если в окружении лежат ручные эксперименты. poetry check --lock проверяет, что lock-файл соответствует pyproject.toml.

Виртуальные окружения и запуск команд

Poetry сам создаёт venv при первом install. Посмотреть путь и версию Python можно через poetry env info. Если в системе несколько интерпретаторов, укажите нужный явно.

poetry env info
poetry env use python3.12
poetry run pytest -q
poetry env remove --all

Команда poetry shell в Poetry 2.x вынесена в отдельный плагин. Если она не найдена, установите poetry-plugin-shell или просто используйте poetry run — второй вариант надёжнее в скриптах.

Сборка, публикация и экспорт

Перед публикацией проверьте, что в пакет не попали тесты, кэш и локальные файлы. Сборка создаёт артефакты в dist/.

poetry build
poetry publish --dry-run
poetry export -f requirements.txt --output requirements.txt --without-hashes

Экспорт нужен там, где развёртывание пока работает на pip: например, в старом Docker-образе или на хостинге с фиксированным пайплайном. Флаг --without-hashes уменьшает размер файла, но лишает проверки целостности.

Poetry в CI

В конвейере достаточно установить Poetry, включить локальное окружение и выполнить установку по lock-файлу. Кэшируйте каталог с пакетами и сам venv, иначе каждая сборка будет скачивать зависимости заново. Версию Poetry фиксируйте в конфигурации CI: обновление мажорной ветки иногда меняет формат lock-файла и поведение solver. Если в матрице несколько версий Python, запускайте установку отдельно для каждой и не переиспользуйте окружение между ними.

python -m pip install --user poetry
poetry config virtualenvs.in-project true
poetry install --sync --without dev
poetry run python -m pytest -q

Типичные ошибки

• Долгий solver. Слишком широкие диапазоны версий увеличивают перебор. Сузьте ограничения по мажорной версии.
• Несовпадение Python. Ограничение requires-python не соответствует интерпретатору в CI — проверьте poetry env info.
• Lock вне git. Без него сборки невоспроизводимы, а код-ревью зависимостей теряет смысл.
• Приватный индекс. Учётные данные храните в keyring или переменных CI, а не в pyproject.toml.
• Смешивание pip и Poetry. Ручной pip install в venv Poetry ломает картину зависимостей.

Чек-лист перед коммитом

• poetry check --lock проходит без ошибок.
• Lock-файл обновлён и добавлен в git.
• Dev-зависимости вынесены в группу, а не в основные.
• В проекте нет паролей и токенов.
• CI устанавливает пакеты через poetry install --sync.

Итог

Poetry закрывает повседневные задачи Python-разработчика: фиксирует зависимости, изолирует окружение и собирает пакеты. Главное — коммитить lock-файл, не смешивать менеджеры и проверять конфигурацию в CI. Начните с poetry init в одном проекте, перенесите зависимости и сравните поведение сборки; после этого переход на Poetry обычно становится постоянным.