Когда вы начинаете писать настоящий проект, перед вами встаёт вопрос: куда ставить сторонние библиотеки? Глобальная установка приводит к хаосу - разные проекты требуют разные версии пакетов, обновление одной библиотеки ломает другой проект. Виртуальное окружение решает это радикально: создаёт изолированное пространство с собственными пакетами и интерпретатором. Это стандарт в профессиональной разработке, игнорирование оборачивается потерей часов на отладку конфликтов.

Зачем нужна изоляция зависимостей

Один проект использует Django 4.2, другой - Django 3.2. Глобально вторая установка перезапишет первую. Виртуальное окружение даёт каждому проекту копию интерпретатора и папку site-packages. Системный Python чист, обновления ОС не ломают проекты, коллега получает идентичную среду одной командой. Конфликт версий - главная причина "у меня работает, а на сервере нет", изоляция устраняет её на корню.

Создание окружения встроенным модулем venv

С Python 3.3 venv в стандартной библиотеке:
CODE0
Создаёт директорию venv с копией интерпретатора, стандартной библиотекой и пустой папкой для пакетов. Имя любое - .venv, env - но venv стандарт. Внутри: bin (Scripts в Windows), lib/python3.x/site-packages, pyvenv.cfg. Размер 20-30 МБ. Флаги: --clear, --upgrade, --prompt "my-project".

Активация в разных ОС

Linux/macOS: source venv/bin/activate
Windows cmd: venv\Scriptsctivate.bat
Windows PowerShell: venv\Scripts\Activate.ps1

Префикс (venv) в терминале - маркер активации. Проверка: which python / where python. Без префикса команды попадут в системный Python.

Fish: source venv/bin/activate.fish

Без активации - прямой вызов:
CODE1
Полезно в CI/CD и cron.

Подробные примеры работы с pip

pip install requests - качает с PyPI в venv/lib/python3.x/site-packages. Версии: pip install "django>=4.2,<5.0", pip install rich==13.7.0. Режим разработки: pip install -e . - изменения видны без переустановки. Все команды pip только внутри venv.

Основные команды pip

install:
pip install requests # последняя
pip install requests==2.31.0 # конкретная
pip install "django>=4.2,<5.0" # диапазон
pip install git+https://github.com/pallets/flask.git@main # GitHub
pip install -e . # разработка
pip install --upgrade requests # обновление
pip install --force-reinstall requests # переустановка
pip install --index-url https://private.pypi.org/simple/ pkg

uninstall: pip uninstall requests, -y - без подтверждения.

show: pip show requests, --files - список файлов.

list: pip list, --outdated, --format=json, --format=freeze.

freeze: pip freeze > requirements.txt, --local - без системных.

Работа с requirements.txt

Фиксация зависимостей:
pip freeze > requirements.txt
Файл в репозиторий. На новой машине: pip install -r requirements.txt. Freeze фиксирует транзитивные зависимости - гарантия воспроизводимости. Для чистоты иногда ведут ручной requirements.in.

Формат requirements.txt requests==2.31.0 django>=4.2,<5.0 numpy git+https://github.com/user/repo.git@main git+https://github.com/user/repo.git@v1.0.0 ./my-package --index-url https://private.pypi.org/simple/ --extra-index-url https://private.pypi.org/simple/ requests==2.31.0 --hash=sha256:abc123...

Установка из requirements.txt pip install -r requirements.txt pip install -r requirements.txt --upgrade pip install -r requirements.txt -r requirements-dev.txt pip install -r requirements.txt -c constraints.txt

Стратегии версионирования Закреплённые: requests==2.31.0, django==4.2.7 - воспроизводимость. Гибкие: requests>=2.31.0,<3.0.0, django>=4.2,<5.0 - автоисправления. Продакшен - закреплённые (freeze или pip-tools), библиотеки - гибкие границы.

requirements-dev.txt для dev-зависимостей

Разделение - лучшая практика. requirements.txt - runtime, requirements-dev.txt - линтеры, тесты, форматтеры.

# requirements.txt
requests==2.31.0
django==4.2.7
psycopg2-binary==2.9.9
redis==5.0.1
# requirements-dev.txt
-r requirements.txt
pytest==7.4.3
pytest-cov==4.1.0
black==23.11.0
ruff==0.1.6
mypy==1.7.1
pre-commit==3.6.0

Установка: pip install -r requirements.txt -r requirements-dev.txt. CI тесты - оба, деплой - только requirements.txt. Уменьшает образ и поверхность атаки.

pip cache и pip config

Кэш pip Кэширует .whl и исходники. Растёт до гигабайт. CODE4 Папка: ~/.cache/pip (Linux), ~/Library/Caches/pip (macOS), %LOCALAPPDATA%\pip\Cache (Windows). PIP_CACHE_DIR - переопределить.

Конфигурация pip Приоритет: ENV → venv/pip.conf → пользовательский → глобальный.

[global]
index-url = https://pypi.org/simple/
extra-index-url = https://private.pypi.org/simple/
timeout = 60
retries = 3
trusted-host = private.pypi.org
disable-pip-version-check = true
format = columns
[install]
user = false
require-hashes = true

Управление:
CODE6
ENV перекрывают: PIP_INDEX_URL, PIP_TIMEOUT, PIP_TRUSTED_HOST, PIP_NO_CACHE_DIR=1, PIP_DISABLE_PIP_VERSION_CHECK=1.

Пример полного workflow

mkdir my-project && cd my-project
python3 -m venv venv --prompt "my-project"
source venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install requests django psycopg2-binary
pip install pytest black ruff mypy pre-commit
pip freeze > requirements.txt
echo "-r requirements.txt" > requirements-dev.txt
echo "pytest==7.4.3" >> requirements-dev.txt
echo "black==23.11.0" >> requirements-dev.txt
echo "ruff==0.1.6" >> requirements-dev.txt
echo "mypy==1.7.1" >> requirements-dev.txt
echo "pre-commit==3.6.0" >> requirements-dev.txt
echo "venv/" >> .gitignore
echo "__pycache__/" >> .gitignore
echo "*.pyc" >> .gitignore
echo ".pytest_cache/" >> .gitignore
echo ".mypy_cache/" >> .gitignore
echo ".ruff_cache/" >> .gitignore
git init && git add . && git commit -m "Initial commit"

Новая машина/CI:
CODE8

pip install -e . для режима разработки

-e создаёт .egg-link/.pth на исходную директорию - изменения видны сразу.

pip install -e .                    # корень пакета
pip install -e ./my-library         # поддиректория
pip install -e ".[dev]"             # с extras
pip install -e ".[test,docs]"

Минимальный pyproject.toml:
CODE10

Структура:
CODE11

После pip install -e .:
CODE12
Изменения в core.py видны сразу.

Когда -e: своя библиотека, отладка форка, монорепо.
Ограничения: не с --target/--prefix, иногда нужен перезапуск для C-расширений, не для продакшена.

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

1. PermissionError ERROR: [Errno 13] Permission denied Решения: активируйте venv; не sudo pip в venv - sudo chown -R $USER:$USER venv; pip cache purge, права на ~/.cache/pip.

2. Конфликт версий ERROR: Cannot install... conflicting dependencies Решения: pip check; pip show -v pkg или pipdeptree; ослабьте требования (верхние границы); pip install --upgrade-strategy=eager; poetry/uv/pip-tools.

3. Устаревшая pip WARNING: You are using pip version 21.3.1... Решение: pip install --upgrade pip. Новый резолвер строже - нормально.

4. Пакет не найден / сеть Решения: проверьте имя на pypi.org; --trusted-host pypi.org; зеркало -i https://pypi.tuna.tsinghua.edu.cn/simple/.

5. Ошибка сборки (no wheel) Решения: системные deps (python3-dev, gcc, libffi-dev, openssl-dev); --only-binary=:all:; pip install --upgrade pip setuptools wheel.

6. Забыли активировать venv Симптомы: pip install работает, python script.py - ModuleNotFoundError. Решение: проверяйте (venv) или which python.

7. Перенос venv между машинами Не работает (пути в shebang, glibc). Решение: только requirements.txt + новая установка. venv в .gitignore.

8. Смешивание pip и conda Conda пакеты - conda install. pip в conda ломает консистентность. Решение: conda install -c conda-forge pkg, pip только для отсутствующих.

Краткий обзор альтернатив: uv, poetry, pdm

Надстройки над venv/pip - poetry, uv, pdm, hatch. Управляют venv, ведут lock-файлы, быстрее. Базовые навыки venv/pip - фундамент: внутри те же venv и pip.

uv - скорость на Rust 10-100x быстрее pip. Astral (Ruff). CODE13 pyproject.toml, uv.lock, совместим с uv pip install -r requirements.txt. CI/CD, крупные проекты.

Poetry - стандарт для библиотек Версионирование, публикация на PyPI. CODE14 pyproject.toml + poetry.lock, группы, семантика версий.

PDM - PEP-совместимый PEP 621, 582, 665. __pypackages__ в проекте. CODE15 pyproject.toml + pdm.lock, PEP 582, экспорт в requirements.txt.

Hatch - workflow PyPA. Матрицы тестирования, билд, плагины. CODE16

Что выбрать | Сценарий | Рекомендация | |----------|--------------| | Учебные, скрипты, простое приложение | venv + pip + requirements.txt | | Библиотека для PyPI | Poetry или PDM | | Крупное приложение, монорепо, CI | uv | | PEP-совместимость, __pypackages__ | PDM | | Матрицы тестирования | Hatch |

Начинайте с venv + pip - переходите к poetry, uv, pdm при необходимости. uv стоит попробовать - миграция минуты, выигрыш в скорости очевиден.

Заключение

Виртуальное окружение - не усложнение, а гигиена. Стоит дешево по сравнению с часами на конфликты в глобальном Python. python3 -m venv venv - первое действие в проекте, активируйте, ставьте зависимости, фиксируете в requirements.txt - забудьте про проблемы с окружением. Следующий урок - итоговый проект: менеджер задач со структурой, тестами, документацией.