Python venv: виртуальное окружение и requirements.txt (пошаговое руководство)

Если вы хотите писать переносимые проекты и не ломать системный Python, начните с правильной основы: виртуальное окружение Python venv и фиксированный список зависимостей в requirements.txt. Ниже — практическое пошаговое руководство с командами, советами и типичными ошибками.

Что такое виртуальное окружение Python venv и зачем оно нужно

venv — это изолированная папка с собственным интерпретатором и пакетами. Вы можете иметь десятки проектов с разными версиями библиотек — они не будут конфликтовать. Это стандартный инструмент, входящий в Python 3.x «из коробки» (python -m venv).

Установка и проверка версии Python

python --version
# или
python3 --version

Если команду не видно, добавьте Python в PATH или используйте установленный лаунчер py на Windows:

py --version

Создание виртуального окружения venv

Обычно окружение складывают в папку .venv внутри проекта:

# В корне проекта
python -m venv .venv
# или, если у вас несколько версий Python
python3 -m venv .venv
# на Windows при наличии лаунчера
py -3 -m venv .venv

Активация окружения

• Windows (PowerShell):

  .venv\Scripts\Activate.ps1
  

  Если видите ошибку про политику выполнения, временно разрешите скрипты:

  Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
  

• Windows (CMD):

  .venv\Scripts\activate.bat
  

• macOS/Linux (bash/zsh):

  source .venv/bin/activate
  

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

deactivate

pip: установка, обновление и удаление пакетов

Лучше вызывать pip через модуль Python — так вы точно используете pip из активного окружения:

python -m pip install --upgrade pip
python -m pip install requests
python -m pip list
python -m pip show requests
python -m pip uninstall requests

requirements.txt: фиксируем зависимости проекта

Файл requirements.txt хранит список библиотек, чтобы любой разработчик мог воспроизвести окружение одной командой. Создать его просто:

# Находясь в активированном venv
python -m pip freeze > requirements.txt

Пример содержимого:

requests==2.32.3
pydantic>=2.8,<3
urllib3==2.2.2

Установка зависимостей из файла:

python -m pip install -r requirements.txt

Советы по работе с requirements.txt:

• Фиксируйте версии для воспроизводимости: package==X.Y.Z или используйте диапазоны (>=,<) для контролируемых апдейтов.
• Не редактируйте файл вручную, если не уверены — лучше обновить пакет и пересобрать requirements.txt через pip freeze.
• Храните requirements.txt под версионированием (Git).

Структура проекта и .gitignore

Виртуальное окружение и кеши не нужны в репозитории. Добавьте .gitignore:

.venv/
env/
__pycache__/
*.pyc
*.pyo
.pytest_cache/
.env

Минимальная структура проекта может выглядеть так:

my_project/
├─ .venv/
├─ app.py
├─ requirements.txt
└─ .gitignore

Частые ошибки и как их избежать

• Проблема: «Установил пакет, но Python его не видит».
  Решение: Убедитесь, что активирован нужный venv и запускаете скрипт тем же интерпретатором. Используйте python -m pip вместо просто pip.
• Проблема: «Сломались глобальные пакеты после установки».
  Решение: Никогда не ставьте зависимости глобально для проектов; всегда используйте venv.
• Проблема: Конфликт версий у разных проектов.
  Решение: У каждого проекта — свой .venv. Не делитесь одним окружением между ними.
• Проблема: «pip» ведет себя странно после обновлений.
  Решение: Обновите pip в активном окружении: python -m pip install --upgrade pip.

Дополнительно: dev и prod зависимости

Иногда удобно разделять зависимости для разработки и продакшена. Простой вариант — два файла:

# requirements.txt (только runtime)
fastapi==0.115.0
uvicorn==0.30.0

# requirements-dev.txt (dev-инструменты)
-r requirements.txt
pytest==8.3.0
black==24.8.0
mypy==1.11.1

Установка для разработки:

python -m pip install -r requirements-dev.txt

Альтернатива для продвинутых: pip-tools (по желанию)

Если хотите точный контроль зависимостей, попробуйте pip-tools:

python -m pip install pip-tools
# Описываем верхнеуровневые зависимости в requirements.in
pip-compile requirements.in  # генерирует requirements.txt с пинами
pip-sync                      # приводит окружение к requirements.txt

Это помогает избежать «дрейфа» зависимостей и делает сборку окружения детерминированной.

Мини-практика: с нуля до запуска скрипта

1. Создайте папку проекта и окружение.

   mkdir weather_app && cd weather_app
   python -m venv .venv
   source .venv/bin/activate   # Windows: .venv\Scripts\Activate.ps1
   

2. Поставьте зависимости и заморозьте их.

   python -m pip install requests
   python -m pip freeze > requirements.txt
   

3. Напишите простой скрипт.

# app.py
import requests

resp = requests.get("https://api.github.com")
print("Status:", resp.status_code)

python app.py

Чек-лист по venv и requirements.txt

• У каждого проекта — свой .venv.
• Используйте python -m pip и обновляйте pip в окружении.
• После установки/обновления пакетов — пересоздавайте requirements.txt через pip freeze.
• Не коммитьте .venv и кеши — добавьте их в .gitignore.
• Для повторяемости окружения используйте pip install -r requirements.txt.

Где прокачаться дальше

Хотите пройти весь путь от основ до продвинутых тем с практикой и разбором типичных ошибок? Рекомендую освоить Python с нуля до гуру по пошаговой программе — структурировано, с примерами и поддержкой.

Итог

Python venv и requirements.txt — фундамент для любого проекта. Настроив один раз, вы избавитесь от конфликтов зависимостей, ускорите онбординг на проект и сможете уверенно выкатывать код на разные машины и серверы. Начинайте каждую новую разработку с создания окружения — и ваш Python-проект скажет спасибо.