Переход с requirements.txt на Poetry: пошаговый план для Python-проектов

Знаете это чувство, когда запускаете проект на новой машине или у коллеги, и всё падает с ошибкой ModuleNotFoundError? Или когда вы обновляете одну библиотеку, а через неделю ломается совсем другая, потому что они конфликтовали по версиям? Если вы работаете с Python дольше пары месяцев, то наверняка сталкивались с хаосом в файле requirements.txt. Это старый добрый стандарт, но он часто превращается в свалку версий без четких границ.

Сегодня мы разберем, как перейти от этого анархического состояния к порядку с помощью Poetry - современного инструмента управления зависимостями для Python. Я не буду грузить вас теорией из учебников. Мы пройдем реальный путь миграции простого проекта, чтобы вы могли повторить эти шаги уже сегодня вечером.

Почему requirements.txt больше не справляется

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

Кроме того, requirements.txt хранит только список установленных пакетов. Он не знает, какие из них нужны для разработки (тесты, линтеры), а какие - только для продакшена. И самое обидное: он не умеет собирать ваш собственный пакет в дистрибутив так же элегантно, как это делают инструменты вроде npm в JavaScript или Cargo в Rust.

Poetry решает эти боли одним махом. Он управляет виртуальными окружениями автоматически, блокирует точные версии зависимостей (lock-файл) и разделяет зависимости на группы. По сути, это менеджер пакетов и сборщик проектов в одном флаконе.

Установка Poetry и подготовка проекта

Прежде чем мигрировать, нужно установить сам инструмент. Официальная рекомендация - использовать скрипт установки, который кладет бинарник в нужную папку. В терминале выполните:

• curl -sSL https://install.python-poetry.org | python3 -

После установки проверьте версию командой poetry --version. Если видите номер версии (например, 1.8.x или новее), значит, всё прошло успешно. Не забудьте добавить путь к бинарнику Poetry в переменную окружения PATH, если команда не находится сразу.

Теперь перейдем в корень вашего существующего проекта. Предположим, там уже лежит код и старый requirements.txt. Нам нужно создать конфигурационный файл pyproject.toml. Это сердце Poetry. Запустите команду:

• poetry init

Мастер настройки спросит имя пакета, версию, автора и лицензию. На вопрос о зависимостях можно пока сказать "no", так как мы будем импортировать их из старого файла чуть позже. После этого в корне появится файл pyproject.toml.

Импорт старых зависимостей

Вам не нужно переписывать список библиотек руками. У Poetry есть встроенная функция для конвертации формата pip. Выполните команду:

• poetry add $(cat requirements.txt)

Эта команда прочитает все строки из requirements.txt и добавит каждую зависимость в секцию [tool.poetry.dependencies] внутри pyproject.toml. Обратите внимание: Poetry может немного изменить формат записи версий. Например, вместо requests==2.28.1 он может записать requests = "^2.28". Это нормально. Символ ^ означает, что Poetry разрешит установку любых минорных и патч-обновлений выше указанной версии, но не позволит перейти на следующую мажорную версию (например, 3.0), которая может содержать ломающие изменения.

Если в вашем requirements.txt были пакеты для разработки, такие как pytest или flake8, лучше выделить их в отдельную группу. Это сделает продакшен-образ легче. Добавьте их командой:

• poetry add pytest flake8 --group dev

Теперь в pyproject.toml появится секция [tool.poetry.group.dev.dependencies]. При деплое на сервер вы сможете игнорировать эту группу, сэкономив место и время сборки.

Генерация lock-файла и создание окружения

После добавления всех зависимостей необходимо зафиксировать точные версии всех транзитивных зависимостей (зависимостей ваших зависимостей). Для этого используется команда:

• poetry lock

Она создаст файл poetry.lock. Этот файл критически важен для воспроизводимости сборки. Он содержит хэши каждой установленной библиотеки и ее точную версию. Никогда не редактируйте poetry.lock вручную и всегда коммитьте его в Git вместе с pyproject.toml.

Наконец, создайте само виртуальное окружение и установите туда пакеты:

• poetry install

Poetry автоматически создаст изолированное окружение в специальной директории (обычно ~/.cache/pypoetry/virtualenvs/) и активирует его при выполнении команд. Вам больше не нужно помнить про source venv/bin/activate. Просто используйте префикс poetry run.

Запуск кода и управление зависимостями в будущем

Как теперь запускать ваши скрипты? Вместо привычного python main.py используйте:

• poetry run python main.py

Это гарантирует, что скрипт использует именно то окружение, которое настроил Poetry. То же самое касается тестов: poetry run pytest.

Что делать, если нужно добавить новую библиотеку? Просто напишите poetry add new-library. Poetry сам обновит pyproject.toml и poetry.lock, а затем переустановит окружение. Хотите удалить ненужный пакет? Используйте poetry remove old-library.

А как быть с обновлением зависимостей? Команда poetry update обновит все пакеты до последних версий, разрешенных правилами в pyproject.toml. Если нужно обновить только один пакет, используйте poetry update package-name. Это гораздо безопаснее, чем слепое pip install --upgrade, которое может сломать всю цепочку зависимостей.

Сравнение инструментов: Pip, Pipenv и Poetry

Стоит ли переходить на Poetry прямо сейчас? Давайте посмотрим на таблицу сравнения популярных инструментов. Данные актуальны для экосистемы Python на октябрь 2026 года.

Как видите, Poetry предлагает лучший баланс между удобством и контролем. Pipenv тоже хорош, но он стал менее популярным после появления Poetry и uv (нового быстрого решателя зависимостей). Однако для большинства командных проектов Poetry остается золотым стандартом благодаря отличной документации и поддержке PyPI.

Частые ошибки при переходе

При первой миграции пользователи часто совершают несколько типичных ошибок. Во-первых, забывают удалить старый requirements.txt или оставить его в репозитории в качестве «запасного». Это путает CI/CD пайплайны. Лучше полностью удалить его после успешного перехода.

Во-вторых, пытаются смешивать команды pip install и poetry add в одном проекте. Если вы установили пакет через pip внутрь poetry-окружения, Poetry об этом не узнает, и при следующем poetry install этот пакет исчезнет. Всегда используйте только команды Poetry.

В-третьих, игнорируют проблему системных зависимостей. Poetry управляет Python-библиотеками, но не системными пакетами Linux (как libpq-dev для PostgreSQL). Эти зависимости по-прежнему нужно устанавливать через apt/yum/brew перед запуском Poetry.

Интеграция с Docker и CI/CD

Для продакшена важно правильно собрать Docker-образ. Вот простой пример Dockerfile для проекта на Poetry:

FROM python:3.11-slim
WORKDIR /app
RUN pip install poetry
COPY pyproject.toml poetry.lock ./
RUN poetry config virtualenvs.create false \
    && poetry install --only=main --no-interaction --no-ansi
COPY . .
CMD ["python", "main.py"]

Обратите внимание на флаг --only=main. Он устанавливает только основные зависимости, пропуская группу dev. Флаг virtualenvs.create false заставляет Poetry устанавливать пакеты в системный Python контейнера, а не создавать лишнюю папку с виртуальным окружением. Это стандартная практика для Docker.

В CI/CD пайплайне (GitHub Actions, GitLab CI) также используйте poetry install. Кэшируйте директорию с виртуальными окружениями Poetry, чтобы ускорить сборки. Путь к кешу обычно выглядит как ~/.cache/pypoetry/virtualenvs.

FAQ