Виртуальное окружение Python venv: создание, активация и зависимости

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

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

Зачем это нужно на практике. Допустим, старый проект работает на Django 4.2, а новый вы начинаете на Django 5. Если ставить все глобально, вторая установка заменит первую, и старый проект сломается. С окружениями у каждого проекта своя версия, и они друг другу не мешают.

Модуль venv входит в стандартную библиотеку Python с версии 3.3, ставить ничего не нужно. На Linux в Debian и Ubuntu глобальная установка через pip и вовсе заблокирована ошибкой externally-managed-environment, так что окружение там фактически обязательно.

Как создать виртуальное окружение venv

1. Откройте терминал в папке проекта. В VS Code это меню Terminal - New Terminal.
2. Выполните команду создания. Последний аргумент - имя папки окружения, общепринятые варианты .venv или venv.
3. Дождитесь окончания: Python скопирует интерпретатор и поставит внутрь pip.

# Windows
python -m venv .venv
# или через лаунчер с выбором версии
py -3.14 -m venv .venv

# Linux и macOS
python3 -m venv .venv

Внутри появится такая структура:

.venv/
  Scripts/        (Windows: python.exe, pip.exe, activate)
  bin/            (Linux, macOS: python, pip, activate)
  Lib/site-packages/   (сюда ставятся библиотеки)
  pyvenv.cfg      (путь к базовому Python и его версия)

Версия Python в окружении всегда та, которой вы его создали. Чтобы сменить версию, окружение пересоздают, обновить его "на месте" нельзя. Если нужной версии нет в системе, сначала поставьте ее: как это сделать и как работает лаунчер py, описано в инструкции по установке Python на Windows.

Как активировать и деактивировать окружение

Активация подменяет в текущем окне терминала команды python и pip на версии из окружения. Команда зависит от системы и оболочки:

После активации в начале строки появится (.venv). Проверить, какой Python сейчас работает, можно так:

python -c "import sys; print(sys.prefix)"

Если в пути есть папка .venv, все в порядке. Выход из окружения - команда deactivate, она одинакова для всех систем.

Активировать окружение не обязательно. Можно вызывать его интерпретатор напрямую: .venv\Scripts\python.exe main.py на Windows или .venv/bin/python main.py на Linux. Так удобно делать в скриптах автозапуска и cron.

Установка пакетов через pip внутри окружения

В активированном окружении pip ставит пакеты только в него. Основные команды:

pip install requests              # последняя версия
pip install "django>=5.0,<6.0"     # версия в диапазоне
pip install pandas==2.2.3         # точная версия
pip install --upgrade requests    # обновить
pip uninstall requests            # удалить
pip list                          # что установлено
pip show requests                 # подробности о пакете
python -m pip install --upgrade pip

Кавычки вокруг django>=5.0,<6.0 нужны, иначе оболочка воспримет символы сравнения как перенаправление вывода. Последняя строка показывает надежную форму вызова: python -m pip гарантирует, что pip относится к тому Python, который вы запускаете. Если команда pip вообще не находится, разбор причин есть в статье "pip не является внутренней или внешней командой".

requirements.txt: как сохранить и восстановить зависимости

Файл requirements.txt - список пакетов проекта с версиями. По нему любой человек воссоздаст ваше окружение одной командой.

Сохранить зависимости

pip freeze > requirements.txt

Получится файл такого вида:

certifi==2025.8.3
charset-normalizer==3.4.3
idna==3.10
requests==2.32.5
urllib3==2.5.0

Установить зависимости на новом месте

1. Склонируйте проект.
2. Создайте окружение: python -m venv .venv.
3. Активируйте его.
4. Выполните pip install -r requirements.txt.

Как вести файл аккуратно

• pip freeze пишет все пакеты, включая зависимости зависимостей. Для приложений это нормально: точные версии дают воспроизводимую сборку.
• Инструменты разработки (pytest, ruff, black) удобно вынести в отдельный requirements-dev.txt, который начинается строкой -r requirements.txt.
• Обновляйте файл после каждой установки нового пакета, иначе коллега получит ImportError.

venv, Git и редактор кода

Папку окружения никогда не коммитят в репозиторий. Она весит десятки мегабайт, содержит пути конкретного компьютера и на другой машине все равно не заработает. В Git попадает только requirements.txt.

# .gitignore
.venv/
venv/
__pycache__/
*.pyc

Как работать с этим в Git, смотрите в шпаргалке по командам Git.

VS Code. Откройте палитру команд (Ctrl + Shift + P), выберите Python: Select Interpreter и укажите интерпретатор из .venv. После этого новые терминалы будут активировать окружение автоматически. Если папка называется .venv и лежит в корне проекта, VS Code обычно предлагает ее сам.

PyCharm. Settings - Project - Python Interpreter - Add Interpreter - Add Local Interpreter - Existing, и путь к python внутри .venv. При создании нового проекта PyCharm может сделать окружение сам.

Частые ошибки при работе с venv

PowerShell: выполнение сценариев отключено в этой системе

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

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Или используйте cmd и activate.bat.

source не является внутренней или внешней командой

Вы запускаете Linux-команду в cmd. На Windows путь идет через Scripts, а не bin, и без source.

The virtual environment was not created successfully because ensurepip is not available

Ошибка на Debian и Ubuntu: модуль venv вынесен в отдельный пакет. Установите его: sudo apt install python3-venv.

Окружение перестало работать после переноса папки

В скриптах активации прописаны абсолютные пути. Перемещать или переименовывать venv нельзя: удалите папку и создайте окружение заново, затем pip install -r requirements.txt.

Пакет установлен, но ModuleNotFoundError

Пакет ушел в другой Python. Проверьте sys.prefix и интерпретатор, выбранный в редакторе.

venv, virtualenv, Poetry, uv: что выбрать

Кроме встроенного venv, есть и другие инструменты. Новичку хватит venv и pip, но названия остальных встречаются в вакансиях и чужих проектах.

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