Виртуальные окружения Python: venv, активация и requirements.txt

Какую проблему решают виртуальные окружения

Установи Python, запусти pip install requests — пакет попадает в единое глобальное место. Для одного проекта это нормально. К третьему начинает болеть:

• Проекту A нужен django==3.2. Проекту B — django==5.0. Только один из них может иметь свою версию установленной глобально.
• Хочется попробовать новую библиотеку, но не хочется, чтобы она загрязняла каждый другой проект на машине.
• Коллега клонирует твой репозиторий — и не понимает, какие версии каких пакетов тебе на самом деле были нужны.

Виртуальное окружение — это ремонт. Самодостаточная папка с Python-интерпретатором и своим каталогом установки библиотек. Когда окружение активировано, python и pip в терминале указывают внутрь этой папки, а не на системный Python. Пакеты, поставленные туда, там и остаются.

Создаём через venv

venv идёт в комплекте с Python 3 — ставить ничего не нужно. Из директории проекта:

python3 -m venv .venv

Это создаст папку .venv/ рядом с кодом. Имя .venv — почти универсальное соглашение; ведущая точка прячет её в большинстве листингов, а редакторы вроде VS Code её автоматически подхватывают.

После команды в папке лежит полная установка Python (десятки мегабайт, это нормально) и свой pip.

Активация

Активация переписывает PATH оболочки так, что python и pip резолвятся в те, что внутри .venv/. Команда зависит от платформы:

# macOS / Linux
source .venv/bin/activate

# Windows (Command Prompt)
.venv\Scripts\activate.bat

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

Пока окружение активно, в приглашении появляется префикс (.venv) — визуальное напоминание. Любой pip install, запущенный сейчас, влияет только на этот проект.

Когда закончил на сегодня, deactivate возвращает предыдущее состояние:

deactivate

Деактивировать перед закрытием терминала не обязательно — выйти из шелла — это то же самое.

Установка пакетов

При активированном окружении ставь, что нужно:

pip install requests
pip install "pandas>=2.0"
pip install --upgrade requests

Проверить установленное — pip list. Удалить — pip uninstall requests.

Установленные пакеты живут под .venv/lib/pythonX.Y/site-packages/. Руками их не правят — каталогом управляет pip.

Фиксация зависимостей через requirements.txt

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

pip freeze > requirements.txt

pip freeze печатает каждый установленный пакет с точной версией. Закоммить файл в git.

Когда коллега (или ты на новой машине) клонирует репозиторий:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Три команды — и окружение совпадает с твоим.

Типовая настройка проекта

Полный рабочий процесс от начала до конца:

# Create the project folder
mkdir my_tool && cd my_tool

# Create and activate the venv
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install requests rich

# Save them
pip freeze > requirements.txt

# Work on your code...
echo "import requests; print(requests.__version__)" > main.py
python main.py

# When you're done
deactivate

Добавь .venv в .gitignore

Никогда не коммить папку .venv/. Она платформо-зависимая и воспроизводима из requirements.txt:

# .gitignore
.venv/
__pycache__/
*.pyc

Коммит раздувает репозиторий, ломается на других машинах и утекает ОС-специфичные бинарники твоего интерпретатора.

Какую версию Python?

По умолчанию python3 -m venv .venv использует тот python3, в который резолвится твой шелл. Если установлено несколько Python-ов (скажем, 3.12 и 3.13), будь явным:

python3.13 -m venv .venv

Когда venv уже создан, его интерпретатор зафиксирован — python внутри активированного venv всегда использует ту самую версию, даже если системный Python изменится.

Когда что-то не так

Несколько типичных симптомов и ремонтов:

• pip install отрабатывает, но импорты падают. Ты поставил в не тот Python. Активируй venv до pip install и перепроверь which python (macOS/Linux) или where python (Windows).
• «ModuleNotFoundError» после активации. venv создавался без определённых библиотек, либо пакет установлен в другое venv. pip list покажет, что реально в текущем.
• Скрипт активации не найден на Windows. PowerShell может блокировать неподписанные скрипты. Выполни один раз Set-ExecutionPolicy -Scope CurrentUser RemoteSigned, чтобы разрешить локальные скрипты.
• «No module named venv». На некоторых дистрибутивах Linux venv — отдельный пакет. sudo apt install python3-venv на Debian/Ubuntu.

За пределами venv: Poetry, uv, pipenv

Когда освоишься с venv + pip + requirements.txt, встретишь инструменты, обёртывающие те же идеи в более приятную эргономику:

• Poetry — управляет venv, зависимостями и сборкой пакета через один pyproject.toml.
• uv — очень быстрая замена pip; умеет и venv.
• pipenv — более старый инструмент, популяризовавший паттерн «Pipfile + Pipfile.lock».

Все они хорошие. Ни один не обязателен для обучения. Сначала освойся с простым venv-потоком; остальное — оптимизации.

Что унести с собой

• У каждого реального Python-проекта своё виртуальное окружение.
• Создавай python3 -m venv .venv, активируй, потом ставь свободно через pip install.
• Фиксируй зависимости через pip freeze > requirements.txt и коммить этот файл.
• Никогда не коммить саму папку .venv/.
• Когда импорты ведут себя странно, сначала проверь, какой Python активен.

Дальше: паттерн __main__

Проект настроен, пакеты поставлены — ещё одна идиома закрывает эту главу: защита if __name__ == "__main__". Она почти в каждом Python-файле, который задуман как скрипт, — об этом следующая страница.