Виртуальные окружения Python: venv, pip и Poetry

Зачем нужно виртуальное окружение

Виртуальное окружение — это отдельная папка со своим интерпретатором Python и своими пакетами. Без него все проекты ставят библиотеки в общий системный Python, и рано или поздно один проект требует одну версию библиотеки, а другой — несовместимую.

Окружение решает три задачи:

• Изоляция: пакеты одного проекта не ломают другой.
• Воспроизводимость: коллега или сервер ставят ровно те же версии.
• Чистая система: не нужно ставить пакеты глобально и с правами администратора.

venv и pip: встроенный вариант

Модуль venv входит в стандартную библиотеку Python, ничего ставить не нужно.

# создать окружение в папке .venv
python -m venv .venv

# активировать: Linux / macOS
source .venv/bin/activate

# активировать: Windows (PowerShell)
.venv\Scripts\Activate.ps1

# установить пакет и зафиксировать версии
pip install requests
pip freeze > requirements.txt

На другой машине окружение восстанавливается так:

python -m venv .venv
# активировать, затем:
pip install -r requirements.txt

pip freeze записывает точные версии всех установленных пакетов, включая транзитивные зависимости. Это просто, но файл не различает «пакеты, которые вы выбрали сами» и «пакеты, которые подтянулись за ними».

Poetry: зависимости и lock-файл

Poetry управляет окружением, зависимостями и сборкой пакета через один файл pyproject.toml. Ставить его удобно через pipx, чтобы он жил отдельно от проектов.

pipx install poetry

poetry init            # создать pyproject.toml в существующем проекте
poetry add requests    # добавить зависимость
poetry add --group dev pytest   # зависимость только для разработки
poetry install         # установить всё по poetry.lock
poetry run python main.py       # запустить внутри окружения

Poetry ведёт два файла:

• pyproject.toml — какие пакеты вам нужны и допустимые диапазоны версий;
• poetry.lock — точные версии, которые реально установлены. Его коммитят в репозиторий.

venv или Poetry

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

• Окружение в git. Папку .venv добавляйте в .gitignore, коммитьте только requirements.txt или pyproject.toml и poetry.lock.
• Забыли активировать. Пакеты молча ставятся в системный Python. Проверьте which python (Linux) или where python (Windows).
• Windows блокирует активацию. PowerShell может запрещать запуск скриптов. Помогает команда Set-ExecutionPolicy -Scope CurrentUser RemoteSigned или запуск через cmd и activate.bat.
• Linux без venv. В некоторых дистрибутивах модуль поставляется отдельным пакетом, например python3-venv. Также там часто нужно писать python3, а не python.
• Ошибка externally-managed-environment. Новые дистрибутивы запрещают pip install в системный Python. Это сигнал создать окружение, а не обходить запрет.
• Перенос папки окружения. Внутри .venv прописаны абсолютные пути, после перемещения его проще пересоздать.