Окружения: venv, Poetry, uv

Окружение это отдельная папка с Python и пакетами для одного проекта. После урока вы создадите окружение тремя способами: venv, Poetry и uv. Потом выберете один.

Осторожно

Правило курса: решайте задания сами, без AI.

Зачем нужны окружения

Без окружения все пакеты лежат в одном месте. Это ломается так:

• Проект A нужен pandas 1.5. Проекту B нужен pandas 2.2. Вместе они не живут.
• Вы поставили пакет, забыли записать. Коллега не может запустить код.
• Установка в системный Python может сломать системные утилиты.

Окружение решает это. У каждого проекта своя папка .venv со своими версиями. Список пакетов записан в файл. Любой человек повторит окружение одной командой.

Термин	Что это
pip	Ставит пакеты из PyPI
venv	Создаёт окружение (встроен в Python)
requirements.txt	Список пакетов с версиями
lock-файл	Точные версии всех пакетов, включая вложенные
pyproject.toml	Описание проекта и его зависимостей

Во всех примерах ниже мы ставим requests и запускаем скрипт app.py:

import requests

print("requests", requests.__version__)

Версии у вас могут отличаться. Это нормально.

Способ 1. pip и venv

Встроено в Python. Ничего ставить не нужно.

macOS / Linux

Проверка:

python3 -m venv --help
python3 -m pip --version

На Ubuntu, если venv нет: sudo apt install python3.14-venv.

Windows

Проверка:

python -m venv --help
python -m pip --version

Практика: venv

Создайте папку проекта и файл app.py (код выше).

macOS / Linux

mkdir venv-demo && cd venv-demo
python3 -m venv .venv
source .venv/bin/activate
which python

Windows

mkdir venv-demo; cd venv-demo
python -m venv .venv
.venv\Scripts\Activate.ps1
where.exe python

Если PowerShell запрещает скрипты: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned. В cmd используйте .venv\Scripts\activate.bat.

Проверка: в начале строки терминала есть (.venv), а which python показывает путь внутри .venv:

/.../venv-demo/.venv/bin/python

Установите пакет и запишите версии:

pip install requests
pip freeze
pip freeze > requirements.txt
python app.py

certifi==2026.10.23
charset-normalizer==3.5.2
idna==3.20
requests==2.34.2
urllib3==2.8.0
requests 2.34.2

pip freeze показывает все установленные пакеты, и ваши, и вложенные.

Выйдите и удалите окружение:

deactivate
rm -rf .venv          # Windows: rmdir /s /q .venv

Восстановите по файлу:

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt     # Windows: .venv\Scripts\pip
.venv/bin/python app.py

requests 2.34.2

Совет

Можно запускать .venv/bin/python app.py без activate. В скриптах и cron так надёжнее.

Минусы связки: нет lock-файла для вложенных пакетов, нет разделения на dev и prod, requirements.txt ведёте вручную.

Способ 2. Poetry

Poetry ведёт зависимости, lock-файл и окружение вместе.

Установка Poetry

Рекомендуемый способ: pipx. Он ставит утилиты в свои изолированные окружения.

macOS

brew install pipx
pipx ensurepath
pipx install poetry
poetry --version

Linux

sudo apt install pipx      # Fedora: sudo dnf install pipx
pipx ensurepath
pipx install poetry
poetry --version

Windows

python -m pip install --user pipx
python -m pipx ensurepath
pipx install poetry
poetry --version

Откройте новый терминал после ensurepath.

Нужен Poetry 2.x. Он хранит зависимости в стандартной секции [project].

Практика: Poetry

Создайте проект и положите в него app.py:

poetry new poetry-demo
cd poetry-demo

Poetry 2.x создаёт структуру с папкой src:

README.md
pyproject.toml
src/
  poetry_demo/
tests/

По умолчанию Poetry хранит окружения в общей папке. Попросите его создать .venv внутри проекта:

poetry config virtualenvs.in-project true --local

Укажите Python 3.14 и добавьте requests:

poetry env use 3.14
poetry add requests

Creating virtualenv poetry-demo in .../poetry-demo/.venv
Using virtualenv: .../poetry-demo/.venv
Using version ^2.34.2 for requests

Updating dependencies
Resolving dependencies...

Package operations: 5 installs, 0 updates, 0 removals

  • Installing certifi (2026.10.23)
  • Installing charset-normalizer (3.5.2)
  • Installing idna (3.20)
  • Installing urllib3 (2.8.0)
  • Installing requests (2.34.2)

Writing lock file

Poetry записал зависимость в pyproject.toml. В Poetry 2.x это выглядит так:

[project]
name = "poetry-demo"
version = "0.1.0"
requires-python = ">=3.14"
dependencies = [
    "requests (>=2.34.2,<3.0.0)"
]

Значение requires-python у вас может быть другим. Poetry берёт его из версии Python, на которой работает сам.

И создал poetry.lock. Это lock-файл. Коммитьте его в git.

Запустите скрипт и посмотрите дерево зависимостей:

poetry run python app.py
poetry show --tree

requests 2.34.2
requests 2.34.2 Python HTTP for Humans.
├── certifi >=2023.5.7
├── charset-normalizer >=2,<4
├── idna >=2.5,<4
└── urllib3 >=1.26,<3

Lock-файл и повтор установки:

poetry lock
poetry install

Если зависимости не менялись, poetry install не ставит пакеты заново. На новой машине он создаст окружение по poetry.lock.

Удалите окружение:

poetry env remove --all

Deleted virtualenv: .../poetry-demo/.venv

В Poetry 2.x команды poetry shell больше нет. Её вынесли в плагин poetry-plugin-shell. Чтобы активировать окружение, есть eval $(poetry env activate). Проще всего использовать poetry run ....

Минусы: медленнее uv. Сам Poetry надо ставить отдельно. Обычно Poetry берёт уже установленный Python. Скачивать Python умеет только команда poetry python install (с версии 2.1, пока экспериментальная).

Способ 3. uv

uv это быстрый менеджер проектов и пакетов на Rust. Он заменяет pip, venv, pip-tools и во многом Poetry. Он умеет сам скачать нужную версию Python.

Установка uv

macOS

brew install uv
uv --version

Или: curl -LsSf https://astral.sh/uv/install.sh | sh

Linux

curl -LsSf https://astral.sh/uv/install.sh | sh
uv --version

Откройте новый терминал после установки.

Windows

winget install --id=astral-sh.uv -e
uv --version

Или: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Практика: uv

Создайте проект на Python 3.14:

uv init uv-demo --python 3.14
cd uv-demo
ls -a

.git  .gitignore  .python-version  README.md  main.py  pyproject.toml

Флаг --python 3.14 делает две вещи:

• пишет 3.14 в файл .python-version;
• пишет requires-python = ">=3.14" в pyproject.toml.

Если 3.14 нет на машине, uv скачает его сам при первом запуске. Сменить версию позже: uv python pin 3.13. Эта команда меняет только .python-version.

Добавьте requests:

uv add requests

Using CPython 3.14.0 interpreter at: /opt/homebrew/opt/python@3.14/bin/python3.14
Creating virtual environment at: .venv
Resolved 6 packages in 2ms
Prepared 4 packages in 3.03s
Installed 5 packages in 5ms
 + certifi==2026.10.23
 + charset-normalizer==3.5.2
 + idna==3.20
 + requests==2.34.2
 + urllib3==2.8.0

В pyproject.toml появилась строка:

dependencies = [
    "requests>=2.34.2",
]

А ещё файл uv.lock с точными версиями и хешами. Коммитьте его в git.

Положите app.py в папку и запустите:

uv run app.py
uv tree

requests 2.34.2
uv-demo v0.1.0
└── requests v2.34.2
    ├── certifi v2026.10.23
    ├── charset-normalizer v3.5.2
    ├── idna v3.20
    └── urllib3 v2.8.0

uv run сам создаёт окружение, если его нет, и синхронизирует пакеты. Активировать ничего не нужно.

Lock и sync:

uv lock
uv sync

Resolved 6 packages in 0.52ms
Audited 5 packages in 0.00ms

Удалите зависимость и верните её:

uv remove requests
uv add requests

Удалите окружение. Оно пересоздаётся командой uv sync:

rm -rf .venv          # Windows: rmdir /s /q .venv
uv sync

Если нужен pip-подобный режим внутри проекта: uv pip install ..., uv pip list. Но для проектов лучше uv add.

Сравнение

	pip + venv	Poetry	uv
Установка	Встроен	Отдельно (pipx)	Один бинарный файл
Lock-файл	Нет (pip freeze)	poetry.lock	uv.lock
Файл зависимостей	requirements.txt	pyproject.toml	pyproject.toml
Скачивает Python	Нет	Экспериментально (2.1+)	Да
Скорость	Обычная	Средняя	Очень высокая
Запуск без activate	.venv/bin/python	poetry run	uv run
Публикация пакета	Нет	Да	Да (uv build, uv publish)

Когда что выбрать:

• venv + pip: быстрый скрипт на чужой машине, где больше ничего нет. Или в Docker-образе, где просто нужен requirements.txt.
• Poetry: в команде уже есть Poetry-проекты. Тогда не меняйте инструмент.
• uv: новый проект, учёба, ETL, ноутбуки. Выбор по умолчанию.

Рекомендация: uv

Используйте uv в этом курсе и в новых проектах.

• Одна утилита вместо трёх.
• Сам ставит нужный Python.
• Быстрый: установка занимает секунды.
• Стандартный pyproject.toml, как у Poetry 2.x. Миграция проста.

В следующих уроках пишите uv run file.py. Если вы выбрали другой инструмент, запускайте так, как показано выше.

Где это в работе

• Каждый ETL-проект имеет свой lock-файл. Так пайплайн на сервере ставит те же версии, что у вас.
• В CI делают uv sync или poetry install, а потом запускают тесты.
• В Docker копируют pyproject.toml и lock-файл, затем ставят зависимости. Это даёт повторяемую сборку.
• .venv не коммитят в git. Коммитят pyproject.toml и lock-файл.

Задания

Задание 1. venv с нуля

Создайте venv, поставьте requests, запишите requirements.txt, удалите .venv и восстановите.

Решение

python3 -m venv .venv
source .venv/bin/activate
pip install requests
pip freeze > requirements.txt
deactivate
rm -rf .venv
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python app.py

Проверка: последняя команда печатает requests 2.34.2 (ваша версия может быть другой).

Задание 2. Какой Python работает?

Активируйте .venv и найдите путь к python. Выйдите и проверьте ещё раз.

Решение

source .venv/bin/activate
which python
deactivate
which python

Проверка: в первом случае путь заканчивается на .venv/bin/python. Во втором путь ведёт в системный или pyenv Python.

Задание 3. Проект на uv

Создайте проект shop-uv на Python 3.14, добавьте requests, запустите app.py.

Решение

uv init shop-uv --python 3.14
cd shop-uv
uv add requests
# создайте app.py из урока
uv run app.py

Проверка: requests 2.34.2. В папке есть uv.lock, а в pyproject.toml строка "requests>=...".

Задание 4. Проект на Poetry

То же самое на Poetry. Затем покажите дерево зависимостей.

Решение

poetry new shop-poetry
cd shop-poetry
poetry env use 3.14
poetry add requests
# создайте app.py из урока
poetry run python app.py
poetry show --tree

Проверка: requests 2.34.2, затем дерево с certifi, charset-normalizer, idna, urllib3. В папке есть poetry.lock.

Задание 5. Повторите окружение на «новой машине»

Удалите .venv в проекте uv и восстановите по lock-файлу. Затем запустите скрипт.

Решение

rm -rf .venv
uv sync
uv run app.py

Проверка: uv sync создаёт .venv и ставит те же версии. Скрипт печатает ту же версию requests.

Задание 6. Выберите инструмент

Для каждой ситуации выберите инструмент и объясните в одном предложении: (а) новый ETL-проект, (б) команда уже на Poetry, (в) одноразовый скрипт на сервере без доступа к установке программ.

Решение

• (а) uv: быстрый, lock-файл, сам ставит Python.
• (б) Poetry: не смешивайте инструменты без причины.
• (в) venv + pip: уже встроены в Python.

Что запомнить

• Один проект, одно окружение. Папку .venv не коммитят.
• Версии фиксируют в lock-файле (uv.lock, poetry.lock) или в requirements.txt.
• uv run file.py и poetry run python file.py работают без activate.
• uv лучший выбор для новых проектов.
• Не ставьте пакеты в системный Python.

Дальше: Переменные и типы данных. Теория: Python Crash Course, глава 1 и приложение B.