Виртуальные окружения Python (venv)

Виртуальное окружение — это самодостаточная директория, содержащая собственную копию интерпретатора Python и отдельную папку site-packages. Пакеты, установленные внутри виртуального окружения, полностью изолированы от системного Python и от всех других окружений на вашем компьютере — поэтому два проекта могут зависеть от разных версий одной и той же библиотеки, не конфликтуя между собой.

В этой главе рассказывается, почему виртуальные окружения важны, как создавать и активировать их с помощью встроенного модуля venv, как управлять зависимостями с pip, а также о повседневном рабочем процессе, которому следует большинство Python-проектов.

Зачем нужны виртуальные окружения

Представьте, что на одной машине у вас есть два проекта:

• Проект A требует requests==2.28.0
• Проект B требует requests==2.31.0

Если установить обе версии в глобальное окружение Python, pip просто перезапишет ту версию, которую установил первой. Один из проектов сломается. Виртуальные окружения решают эту проблему, давая каждому проекту собственную изолированную директорию site-packages, так что обе версии сосуществуют, не влияя друг на друга.

Другие практические преимущества:

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

Python 3.3 и новее включают venv в стандартную библиотеку — установка не требуется.

python -m venv .venv

Эта команда создаёт директорию .venv в текущей папке. Имя .venv — общепринятое соглашение (ведущая точка скрывает её в Unix-подобных системах), но можно использовать любое имя — env, venv или даже специфичное для проекта.

Что venv создаёт внутри .venv:

.venv/
├── bin/           # Python interpreter + activation scripts (Linux/macOS)
│   ├── activate
│   ├── python -> python3
│   └── pip
├── include/
├── lib/
│   └── python3.x/
│       └── site-packages/   # Installed packages go here
└── pyvenv.cfg               # Records the Python version and base prefix

На Windows структура немного отличается — bin/ называется Scripts/, а разделители путей — обратные косые черты.

Выбор конкретной версии Python

Если у вас установлено несколько версий Python, укажите интерпретатор явно:

python3.11 -m venv .venv

Или на Windows:

py -3.11 -m venv .venv

Файл pyvenv.cfg внутри окружения записывает, какой интерпретатор был использован, поэтому окружение всегда запускается с этой версией.

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

Создание окружения не означает его автоматического использования. Необходимо активировать его — это добавляет директорию bin/ окружения в начало PATH, чтобы python и pip указывали на копии из окружения.

macOS и Linux:

source .venv/bin/activate

Windows (Командная строка):

.venv\Scripts\activate.bat

Windows (PowerShell):

.venv\Scripts\Activate.ps1

После активации в командной строке оболочки обычно отображается имя окружения в скобках:

(.venv) $ python --version
Python 3.12.3
(.venv) $ which python
/your/project/.venv/bin/python

Любая команда pip install, выполненная при активном окружении, устанавливает пакеты в .venv/lib/.../site-packages/, но не в системный Python.

Деактивация

Когда вы закончили работу над проектом или хотите переключиться на другое окружение:

deactivate

Командная строка оболочки возвращается к обычному виду, а python снова указывает на системный интерпретатор.

Установка пакетов внутри виртуального окружения

При активном окружении используйте pip обычным образом:

pip install requests flask

Убедитесь, что пакеты попали в нужное место:

pip show requests

Строка Location: в выводе должна указывать на вашу директорию .venv.

Просмотр установленных пакетов

pip list

Только что созданное окружение, как правило, содержит только pip и setuptools. Всё остальное — то, что вы (или файл requirements) установили явно.

Сохранение и восстановление зависимостей

Экспорт файла requirements

После настройки окружения зафиксируйте точные версии пакетов, чтобы любой мог их воспроизвести:

pip freeze > requirements.txt

Типичный файл requirements.txt выглядит так:

certifi==2024.2.2
charset-normalizer==3.3.2
flask==3.0.3
idna==3.6
requests==2.31.0
urllib3==2.2.1

Зафиксируйте requirements.txt в системе контроля версий. Не фиксируйте саму директорию .venv — добавьте её в .gitignore.

Восстановление из файла requirements

На новой машине или в свежем клоне:

python -m venv .venv
source .venv/bin/activate        # or the Windows equivalent
pip install -r requirements.txt

Это воссоздаёт окружение, идентичное тому, которое вы зафиксировали.

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

Большинство Python-проектов следуют этой последовательности:

# 1. Clone the repository
git clone https://github.com/example/myproject.git
cd myproject

# 2. Create a virtual environment
python -m venv .venv

# 3. Activate it
source .venv/bin/activate

# 4. Install dependencies
pip install -r requirements.txt

# 5. Work on the project ...

# 6. When you add a new package, update the requirements file
pip install newpackage
pip freeze > requirements.txt

Что добавить в .gitignore

Никогда не фиксируйте директорию окружения в системе контроля версий — она содержит скомпилированные бинарные файлы, зависит от платформы и может занимать десятки мегабайт. Добавьте один из следующих шаблонов в .gitignore:

# Virtual environment
.venv/
venv/
env/

Фиксируйте только requirements.txt (или pyproject.toml + requirements.txt). Этого достаточно для пересоздания окружения с нуля.

venv и альтернативные инструменты

venv — встроенное решение, достаточное для большинства случаев. Вы также можете встретить следующие альтернативы:

Для большинства начинающих и несложных проектов python -m venv — правильный выбор: он поставляется вместе с Python и не требует дополнительной установки.

Типичные ошибки и их устранение

«python: command not found» при создании окружения

В некоторых дистрибутивах Linux Python 3 вызывается как python3, а не python:

python3 -m venv .venv

PowerShell отказывается запускать скрипт активации

По умолчанию Windows PowerShell блокирует неподписанные скрипты. Включите выполнение скриптов для текущего пользователя:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Затем снова запустите скрипт активации.

Пакеты установлены, но import не работает

Скорее всего, вы забыли активировать окружение. Выполните:

source .venv/bin/activate

Затем попробуйте выполнить import снова. Узнать, какой Python активен, можно с помощью which python (macOS/Linux) или where python (Windows).

Окружение ссылается на удалённую установку Python

Если вы обновили Python и удалили старую версию, ссылки venv перестают работать. Просто пересоздайте окружение:

rm -rf .venv
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Таблица быстрого справочника

Связанные главы

• Python pip — полное руководство по установке, обновлению и удалению пакетов
• Python Modules — как работает система импорта Python
• Python Packages — организация собственного кода в устанавливаемые пакеты

Практика