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

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