Перейти к содержимому
Учи.Онлайн Выбрать школу
Статья

venv, Poetry и uv: как держать зависимости Python-проекта в порядке и не ломать систему

Чтобы зависимости Python-проекта не конфликтовали между собой и с системой, каждому проекту заводят своё виртуальное окружение — папку с отдельным интерпретатором и библиотеками, — а список нужных пакетов записывают в файл проекта. Встроенный набор — модуль venv и pip с файлом requirements.txt. Poetry и uv берут на себя больше: сами создают окружение, ведут pyproject.toml и записывают точные версии всех пакетов в lock-файл. Ниже — чем эти слои отличаются, один учебный проект тремя способами, частые ошибки и что проверить в программе обучения.

Автор: редакция Учи.ОнлайнОтветственный редактор: Дмитрий Игнатьев
Содержание
Иллюстрация к статье: venv, Poetry и uv: как держать зависимости Python-проекта в порядке и не ломать систему

Главное заблуждение новичка — считать окружение ценной частью проекта: копировать папку .venv на другой компьютер, класть её в Git, бояться удалить. Документация модуля venv говорит обратное: окружение одноразовое, его легко удалить и создать заново, в Git его не добавляют и не переносят, а на новом месте создают ещё раз. Ценна не сама папка, а файл, по которому её можно восстановить за минуту.

Что изолирует окружение и почему без него всё ломается

Представьте два проекта на одном ноутбуке: старому отчёту нужна pandas 1.5, новому — 2.2. В общем интерпретаторе побеждает последняя установка, и один проект перестаёт запускаться. В окружении у каждого проекта своя папка site-packages, и pip install не трогает ни соседей, ни системный Python.

На Linux системным интерпретатором пользуются утилиты дистрибутива, поэтому свежие версии Debian и Ubuntu на pip install в него отвечают ошибкой externally-managed-environment. Этот механизм подробно разобран в нашей статье о Python для сисадмина и DevOps-инженера; здесь важен вывод: библиотеки для своих программ ставят только в окружение.

Почему окружение нельзя скопировать, тоже объясняет документация venv. Скрипты, которые pip кладёт в окружение, работают без активации, поэтому в их первой строке записан абсолютный путь к интерпретатору. Переименовали папку проекта — путь устарел, и pytest перестаёт запускаться. С Python 3.13 venv по умолчанию создаёт в папке окружения .gitignore, исключающий её из Git целиком.

Три слоя: список зависимостей, lock-файл и окружение

Порядок в зависимостях держится на трёх разных вещах, и их путаница — источник большинства проблем. Список прямых зависимостей пишет человек: что нужно проекту и в каких пределах версий, например requests>=2.31. Lock-файл генерирует инструмент: в нём точные версии всех пакетов, включая зависимости зависимостей, и хеши файлов. Окружение собирают по lock-файлу и в любой момент пересоздают.

У pip оба первых слоя живут в одном формате: requirements.txt бывает и списком «что нужно», и снимком pip freeze. Современный способ — раздел [project] с полем dependencies в pyproject.toml. С версии 2.0 его рекомендует и документация Poetry, а uv работает с ним изначально.

Lock-файлы долго были у каждого инструмента свои: poetry.lock, uv.lock, файлы pip-tools. В марте 2025 года принят PEP 751, который ввёл общий формат — pylock.toml. Файл обязан указывать версию формата (lock-version = "1.0"), для каждого архива или wheel-файла пакета хранит хотя бы один хеш и устроен так, чтобы установщику не приходилось заново подбирать версии. При этом PEP оговаривает, что requirements-файлы он полностью не заменяет, и на практике стандарт стал форматом обмена, а не единым файлом для всех. В pip команда pip lock помечена как экспериментальная, и её результат гарантированно подходит только для текущей версии Python и платформы. uv умеет выгрузить pylock.toml командой uv export --format pylock.toml, но в описании структуры проекта прямо сказано, что внутри проекта uv продолжит пользоваться своим uv.lock — универсальным, рассчитанным сразу на разные платформы. Отсюда правило: в репозиторий коммитят lock-файл того инструмента, которым работает команда, а pylock.toml выгружают, когда устанавливать будет другой инструмент.

venv и pip, Poetry, uv: в чём разница

Все три варианта решают одну задачу, но берут на себя разный объём работы — таблица показывает, что останется делать руками.

Инструмент Что делает Где записаны зависимости Точные версии
venv + pip создаёт окружение и ставит пакеты requirements.txt снимок pip freeze
Poetry окружение, подбор версий, сборка и публикация пакета pyproject.toml poetry.lock
uv то же плюс установка нужной версии Python pyproject.toml uv.lock

Встроенного набора хватает для скрипта, учебного задания и небольшого сервиса: он есть везде, где есть Python. Poetry удобен для библиотек, которые публикуют на PyPI; окружения он по умолчанию хранит в своём кеше, а не в папке проекта (настройка virtualenvs.in-project). uv создаёт .venv рядом с pyproject.toml и сам скачивает нужную версию Python командой uv python install, то есть может заменить pyenv.

Учебный пример: один проект тремя способами

Учебная ситуация: аналитик пишет скрипт report.py, который забирает данные по API и сохраняет таблицу в Excel. Нужны requests и openpyxl.

Через venv и pip на Linux или macOS:

python3 -m venv .venv
.venv/bin/python -m pip install requests openpyxl
.venv/bin/python -m pip freeze > requirements.txt
.venv/bin/python report.py

Активировать окружение не обязательно: документация venv разрешает вызывать его интерпретатор по полному пути (в Windows — .venv\Scripts\python). Коллега восстанавливает окружение командой pip install -r requirements.txt.

Через Poetry: poetry init, затем poetry add requests openpyxl — он допишет зависимости и создаст poetry.lock; запуск — poetry run python report.py. Коллега выполняет poetry install и получает ровно версии из lock-файла.

Через uv: uv init, uv add requests openpyxl и uv run report.py. uv сам создаст .venv, запишет uv.lock и перед запуском сверит с ним окружение. Коллеге после клонирования хватит uv sync.

С чего начать и в каком порядке осваивать

Порядок ниже идёт от того, что есть в любой установке Python, к инструментам, которые это автоматизируют. Начав сразу с uv, легко не понять, что он делает за вас, и растеряться на сервере, где есть только pip.

  1. Создайте окружение через python -m venv, поставьте пакет, удалите папку и пересоздайте её.
  2. Научитесь запускать pip как python -m pip: так пакет точно попадёт в тот интерпретатор, который вы вызвали.
  3. Сохраните зависимости в requirements.txt и восстановите окружение в чистой папке.
  4. Опишите тот же проект в pyproject.toml и переведите его на Poetry или uv.
  5. Вынесите pytest и линтер в группу зависимостей для разработки.
  6. Соберите пакет и опубликуйте его на тестовом сервере TestPyPI.

После каждого шага клонируйте репозиторий в новую папку и запустите проект командами из README. Если понадобилось что-то, о чём README молчит, файл зависимостей неполон.

Обычно этот навык осваивают по ходу обучения веб-разработке или самому языку. Например, на курсе «Python-фреймворк Django» от Skillbox pip и virtualenv названы среди рабочих инструментов наряду с Git и PyCharm. Практические задания проверяет куратор, а итоговый проект — бэкенд интернет-магазина, где без описанных зависимостей не обойтись.

Открыть курс «Python-фреймворк Django»

Типичные ошибки и как себя проверить

Самая частая ошибка — пакет установлен, а импорт не работает. Обычно pip относится к одному интерпретатору, а программа запускается другим: системным или выбранным в редакторе. Помогают вызов python -m pip и команда python -c "import sys; print(sys.executable)", которая покажет, какой интерпретатор работает на самом деле.

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

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

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

Чему учат на онлайн-курсах

В программах переподготовки по Python окружениям отводят часть модуля. На курсе «Python программист» от ЭКОДПО виртуальное окружение изучают вместе с визуализацией данных, а в одной из дисциплин разбирают тесты и публикацию пакетов на PyPI. Обучение идёт самостоятельно, по текстовым урокам и тестам, итог — диплом о профессиональной переподготовке.

Открыть курс «Python программист — переподготовка»

В учебном плане не названы ни Poetry, ни uv, а проверка кода наставником не описана. Если нужны современные инструменты, уточните у школы, какие версии Python и менеджеры зависимостей используются в заданиях.

Похожий набор тем есть на курсе «Python программист» от АПОК: модуль «Визуализация данных и виртуальное окружение» на 34 часа и модуль «Написание тестов и публикация пакетов на PyPI» — тоже на 34 часа. Школа прямо пишет, что преподавателей, код-ревью и проверки заданий нет, так что практику придётся строить самостоятельно — например, по плану из раздела о первых шагах.

Открыть курс «Python программист»

Сравнивая программы, смотрите не на слово «окружение» в названии модуля, а на задания: есть ли проект, который нужно запустить с нуля по README, и проверяет ли кто-нибудь ваш pyproject.toml.

Как навык влияет на доход

Управление зависимостями — не отдельная профессия, а часть базовых требований к Python-разработчику, аналитику и инженеру данных. Открытых данных о надбавке за знание Poetry или uv найти не удалось, поэтому цифр не будет. Навык работает иначе: он позволяет брать задачи по сборке и выкладке проекта, а тестовое задание, которое запускается одной командой, выглядит убедительнее того, что «работало на моём компьютере».

Чтобы оценить картину самостоятельно, найдите на сайте вакансий «Python» вместе с «Poetry» или «uv», задайте регион и опыт и сравните зарплаты с выдачей просто по «Python». Смотрите, указана ли сумма до вычета налога или на руки, и помните, что выборка по узкому запросу бывает маленькой.

Что выбрать для своего проекта

Для учебных скриптов и первых проектов хватает venv и pip: они научат главному — окружение одноразовое, а описание зависимостей хранится в файле. Если вы пишете библиотеку или пришли в команду, где уже есть poetry.lock, осваивайте Poetry. Новый проект с нуля удобно начинать на uv, особенно когда нужна определённая версия Python. Если хотите учиться системно, сравните школы в рейтинге онлайн-школ с обучением Python — он широкий, по всему направлению, поэтому про окружения и менеджеры зависимостей уточняйте программу каждого курса отдельно.