Виртуальное окружение Python (venv) это отдельная папка проекта со своим интерпретатором и своим набором библиотек. Создаётся одной командой: python3 -m venv .venv на macOS и Linux или py -m venv .venv на Windows. Включается командой source .venv/bin/activate, на Windows командой .venv\Scripts\activate.
После активации pip install ставит пакеты только в этот проект, а соседние проекты и системный Python остаются нетронутыми. Если Python ещё не установлен, начните с инструкции как скачать и установить Python на Windows, macOS и Linux.
Ниже собраны команды с реальным выводом (Python 3.14.7 на macOS и 3.12.3 на Ubuntu 24.04), отличия Windows и ошибки, на которых застревают чаще всего.
CheckroiПодборка курсов по Python566 курсов • 51 школаСравните цены, школы, программу и найдите выгодные предложения по обучениюСравнить→
Что такое виртуальное окружение и зачем оно нужно
Все библиотеки, которые вы ставите через pip без окружения, попадают в одну общую папку Python. Пока проект один, это незаметно. Проблемы начинаются со второго.
В учебнике Python на docs.python.org приведён пример такого конфликта: приложению A нужна версия 1.0 модуля, приложению B нужна 2.0. В одну установку Python обе версии не поместятся, и одно из приложений перестанет работать. С отдельным окружением у каждого проекта своя версия, и обновление в проекте B никак не задевает проект A.
Что даёт venv на практике:
- Изоляция зависимостей. Django 4 в одном проекте и Django 5 в другом живут рядом без конфликтов. Для Django-разработчика, который ведёт несколько сайтов на разных версиях фреймворка, это обычная ситуация.
- Воспроизводимость. Список пакетов сохраняется в
requirements.txt, и проект поднимается на другом компьютере за пару минут. - Чистый системный Python. На Ubuntu 24.04 и в Python из Homebrew pip вне окружения вообще отказывается ставить пакеты, об этом ниже в разделе об ошибках.
Модуль venv входит в стандартную библиотеку, ставить его не нужно. С версии 3.5 документация называет его рекомендуемым способом создания виртуальных окружений.
Как создать виртуальное окружение venv
Окружение создают в папке проекта и обычно называют .venv: так делает руководство Python Packaging. Почему именно так, объясняет учебник Python: точка в начале обычно прячет папку в терминале, а имя не путается с файлом настроек .env.
- Откройте терминал (на Windows командную строку или PowerShell).
- Перейдите в папку проекта:
cd путь/к/проекту. - Выполните команду создания окружения для своей системы.
- Проверьте, что в проекте появилась папка
.venv.
macOS и Linux:
python3 -m venv .venvWindows:
py -m venv .venvКоманда работает молча и на нашем Mac заняла около полутора секунд. Вот что лежит внутри созданной папки (macOS, Python 3.14.7):
$ ls -a .venv
. .. .gitignore bin include lib pyvenv.cfg
$ ls .venv/bin
Activate.ps1 activate activate.csh activate.fish
pip pip3 pip3.14 python python3 python3.14 𝜋thon| Что в папке | Зачем |
|---|---|
bin (на Windows Scripts) |
ссылка на интерпретатор, pip и скрипты активации |
lib/python3.X/site-packages (на Windows Lib\site-packages) |
сюда pip ставит библиотеки проекта |
pyvenv.cfg |
путь к базовому Python и его версия |
.gitignore |
прячет окружение от Git, появился в Python 3.13 |
Файл .gitignore внутри окружения появился в Python 3.13: в документации venv сказано, что с этой версии он создаётся по умолчанию, отключить можно флагом --without-scm-ignore-files. На Python 3.12 и более ранних версиях папку .venv в .gitignore проекта добавляют руками. Зачем это нужно, если вы ещё не работали с репозиториями, объясняет статья Git простыми словами.
Ещё два полезных флага: --prompt имя меняет подпись окружения в строке терминала, а --upgrade-deps сразу обновляет pip до последней версии.
Как активировать venv в Windows, macOS и Linux
Активация добавляет папку bin (или Scripts) окружения в начало PATH. После этого команды python и pip берутся из окружения, а не из системы. Команда зависит от оболочки, таблица составлена по документации venv:
| Система и оболочка | Команда активации |
|---|---|
| macOS, Linux: bash или zsh | source .venv/bin/activate |
| fish | source .venv/bin/activate.fish |
| csh, tcsh | source .venv/bin/activate.csh |
| Windows: cmd.exe | .venv\Scripts\activate.bat |
| Windows: PowerShell | .venv\Scripts\Activate.ps1 |
Если всё получилось, в начале строки терминала появится имя окружения в скобках, например (.venv). Надёжнее проверить, откуда запускается Python:
(.venv) $ which python
/Users/.../myproject/.venv/bin/python
(.venv) $ python -c "import sys; print(sys.prefix != sys.base_prefix)"
TrueПроверку через sys.prefix != sys.base_prefix предлагает сама документация Python: внутри окружения выражение даёт True, в системном интерпретаторе — False. На Windows вместо which python используйте where python.
Можно не активировать
Документация venv прямо говорит, что активировать окружение не обязательно. Можно напрямую вызвать интерпретатор из окружения: .venv/bin/python main.py на macOS и Linux или .venv\Scripts\python main.py на Windows.
Так удобно запускать скрипты из cron и при деплое, где интерактивного терминала нет. Для первой пробы подойдёт любой скрипт, например из подборки простых примеров кода на Python.
Как выйти из окружения и удалить его
Выйти из окружения можно командой deactivate в любой оболочке. Закрыть окно терминала тоже работает: в новом окне окружение придётся активировать заново.
Отдельной команды удаления у venv нет, окружение удаляют вместе с папкой:
- macOS и Linux:
rm -rf .venv - Windows, cmd.exe:
rmdir /s /q .venv
Код проекта при этом не пострадает. Если зависимости записаны в requirements.txt, окружение пересоздаётся за минуту, поэтому удалять его не страшно.
Установка пакетов и requirements.txt
В активированном окружении pip работает как обычно, только пакеты ложатся в .venv. Свежее окружение почти пустое:
(.venv) $ pip list
Package Version
------- -------
pip 26.2.1Ставим библиотеку и фиксируем список зависимостей командой pip freeze:
(.venv) $ pip install requests
(.venv) $ pip freeze > requirements.txt
(.venv) $ cat requirements.txt
certifi==2026.7.22
charset-normalizer==3.5.2
idna==3.20
requests==2.34.2
urllib3==2.8.0Одна команда pip install requests подтянула ещё четыре пакета: это зависимости самой requests. Именно поэтому список лучше снимать через pip freeze, а не писать по памяти.
На другом компьютере или после удаления окружения всё восстанавливается тремя командами:
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txtМы проверили: новое окружение получило те же пять пакетов тех же версий. Само окружение с requests весит около 17 МБ, поэтому в репозиторий кладут requirements.txt, а папку .venv не кладут. Подробнее о pip и ошибке ModuleNotFoundError на живом примере — в инструкции как установить PyGame.
Виртуальное окружение в VS Code и PyCharm
Редакторы умеют создавать окружение сами и подхватывают уже созданное.
VS Code
По документации VS Code расширение Python ищет окружения в рабочей папке по шаблону ./**/.venv, поэтому папка .venv в проекте находится автоматически.
- Откройте палитру команд:
Ctrl+Shift+P(на MacCmd+Shift+P). - Выберите Python: Select Interpreter.
- Укажите интерпретатор из
.venv.
Если окружения ещё нет, быстрое создание из того же расширения назовёт его .venv. Как создать и запустить первый файл в редакторе, разобрано в статье как создать и запустить файл Python в VS Code.
PyCharm
Пункты ниже приведены по справке JetBrains и названы так, как в английском интерфейсе.
- Нажмите на переключатель интерпретатора в строке состояния и выберите Add New Interpreter → Add Local Interpreter.
- Выберите тип окружения Virtualenv, в качестве базового интерпретатора укажите свой Python, а в поле Location папку окружения.
- Подтвердите OK.
Если открыть в PyCharm папку с requirements.txt и без окружения, редактор сам предложит создать его и поставить все пакеты из списка.
Канал основателя Checkroi Вани БуявцаЗабирайте промпты и обучение по нейросетям в моём Телеграм-каналеБольше 3 700 человек уже применяют Claude Code, ChatGPT и другие нейросети в работе, учёбе, бизнесе и жизниПерейти в каналvenv, virtualenv, conda, uv и Poetry: что выбрать
Встроенного venv хватает для учёбы и большинства рабочих проектов. Другие инструменты решают задачи, которые venv не закрывает.
| Инструмент | Чем отличается | Когда брать |
|---|---|---|
| venv | встроен в Python, ничего ставить не нужно | по умолчанию, для учёбы и большинства проектов |
| virtualenv | отдельный пакет: часть его возможностей с Python 3.3 вошла в стандартную библиотеку как venv; создаёт окружение для любой установленной версии Python и расширяется плагинами | когда в проекте нужна другая версия Python, а uv не используете |
| conda | ставит не только Python-пакеты, но и сам Python нужной версии: conda create -n myenv python=3.9 |
анализ данных и научные библиотеки |
| uv | команда uv venv создаёт .venv и может взять другую версию Python через --python 3.11 |
когда важна скорость и нужно держать несколько версий Python |
| Poetry | ведёт зависимости в pyproject.toml, окружения по умолчанию хранит в своей папке кеша |
библиотеки и проекты, которые публикуют как пакет |
Мы проверили uv venv на том же Mac: он создал .venv и сам выбрал установленный Python 3.13.13. Активируется такое окружение теми же командами, что и обычное.
Частые ошибки и что с ними делать
error: externally-managed-environment
Симптом: pip install вне окружения падает с этой ошибкой. Мы получили её в Python из Homebrew на macOS, на Ubuntu 24.04 в системном Python лежит тот же запрет (файл EXTERNALLY-MANAGED).
Причина: механизм из PEP 668. Система помечает свой Python как управляемый пакетным менеджером, и pip по умолчанию не ставит в него пакеты, а отправляет в виртуальное окружение.
Решение: создать venv и ставить пакеты внутри него. Флаг --break-system-packages снимает запрет, но может сломать системные программы на Python.
На Ubuntu или Debian venv не создаётся
Симптом: python3 -m venv .venv завершается ошибкой, и окружение не создаётся.
Причина: в Ubuntu модуль вынесен в отдельный пакет python3-venv. На нашем сервере с Ubuntu 24.04 он стоит как python3.12-venv, и окружение создаётся без ошибок.
Решение: sudo apt install python3-venv, затем повторить команду.
PowerShell не запускает Activate.ps1
Симптом: при активации PowerShell сообщает, что выполнение сценариев отключено. Документация venv предлагает разрешить скрипты для текущего пользователя:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserЕсли менять политику не хочется, активируйте окружение из cmd.exe через activate.bat.
Перенёс папку проекта, и всё сломалось
Симптом: после переименования или переноса папки команды из окружения не запускаются. Так выглядит ошибка у pip:
$ ../moved_venv/bin/pip --version
bad interpreter: /.../myproject/.venv/bin/python3.14: no such file or directoryПричина: в скриптах окружения записан абсолютный путь к интерпретатору, и документация venv прямо называет окружения непереносимыми.
Решение: удалить .venv и создать заново по requirements.txt. Копировать окружение между компьютерами тоже бесполезно.
Пакет установлен, а import не работает
Симптом: pip install прошёл, а скрипт пишет ModuleNotFoundError. Обычно пакет ушёл в другой Python: окружение не было активно, или редактор запускает код системным интерпретатором.
Решение: проверить which python (на Windows where python), выбрать интерпретатор из .venv в редакторе и ставить пакеты командой python -m pip install, она всегда ставит в тот Python, которым вызвана.
Где освоить Python системно
С виртуального окружения начинается порядок в проекте. Дальше идут структура кода, тесты, работа с Git и деплой, и в одиночку собрать это в систему долго. Если хотите понять, куда это ведёт, начните со статей кто такой Python-разработчик и как стать Python-разработчиком с нуля.
Курсы с практикой на реальных проектах собраны в каталоге курсов Python: там можно сравнить программы по цене, длительности и формату.
| Курс | Школа | Стоимость со скидкой | В рассрочку | Длительность | Обзор курса от Checkroi |
|---|---|---|---|---|---|
| Профессия «Python-разработчик» Перейти на сайт курса |  Skillbox | 157 335 ₽ | 5987 ₽/мес. | 10 месяцев | Обзор курса |
| Fullstack-разработчик на Python Перейти на сайт курса |  Нетология | 161 200 ₽ | 7125 ₽/мес. | 21 месяц | Обзор курса |
| ДО Профессия Python-разработчик Перейти на сайт курса |  GeekBrains | 149 001 ₽ | 3167 ₽/мес. | 10 месяцев | Обзор курса |
| Автоматизированное тестирование на Python Перейти на сайт курса | Skillbox | 118 666 ₽ | 4108 ₽/мес. | 9 месяцев | Обзор курса |
| Программирование на Python ПРО Перейти на сайт курса | Skillbox | 119 600 ₽ | - | 17 месяцев | Обзор курса |
Больше программ — в полном каталоге курсов по Python
