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
Активация окружения
.venvScriptsActivate.ps1
Если видите ошибку про политику выполнения, временно разрешите скрипты:
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
.venvScriptsactivate.bat
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
Частые ошибки и как их избежать
Решение: Убедитесь, что активирован нужный
venv и запускаете скрипт тем же интерпретатором. Используйте python -m pip вместо просто pip.Решение: Никогда не ставьте зависимости глобально для проектов; всегда используйте
venv.Решение: У каждого проекта — свой
.venv. Не делитесь одним окружением между ними.Решение: Обновите 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
Это помогает избежать «дрейфа» зависимостей и делает сборку окружения детерминированной.
Мини-практика: с нуля до запуска скрипта
- Создайте папку проекта и окружение.
mkdir weather_app && cd weather_app python -m venv .venv source .venv/bin/activate # Windows: .venvScriptsActivate.ps1 - Поставьте зависимости и заморозьте их.
python -m pip install requests python -m pip freeze > requirements.txt - Напишите простой скрипт.
# 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-проект скажет спасибо.
