venv.md
1> **Источник:** https://python-all.ru/3.7/library/venv.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`venv`](https://python-all.ru/3.7/library/venv.html#module-venv) – Создание виртуальных окружений89Новое в версии 3.3.1011**Исходный код:** [Lib/venv/](https://python-all.ru/src/3.7/Lib/venv)1213---1415Модуль [`venv`](https://python-all.ru/3.7/library/venv.html#module-venv) предоставляет поддержку создания легковесных «виртуальных окружений» со своими собственными каталогами сайт-пакетов, опционально изолированными от системных каталогов сайт-пакетов. Каждое виртуальное окружение имеет свой собственный двоичный файл Python (который соответствует версии двоичного файла, использованного для создания этого окружения) и может иметь свой независимый набор установленных пакетов Python в своих каталогах сайт-пакетов.1617За дополнительной информацией о виртуальных окружениях Python обращайтесь к [**PEP 405**](https://python-all.ru/3.7/library/venv.html).1819> **См. также**20>21> [Руководство пользователя по упаковке Python: создание и использование виртуальных окружений](https://python-all.ru/3.7/library/venv.html)2223> **Примечание**24>25> Скрипт `pyvenv` устарел начиная с Python 3.6 в пользу использования `python3 -m venv`, чтобы предотвратить возможную путаницу относительно того, на каком интерпретаторе Python будет основано виртуальное окружение.2627## Создание виртуальных окружений2829Создание [виртуальных окружений](https://python-all.ru/3.7/library/venv.html#venv-def) выполняется с помощью команды `venv`:3031```python32python3 -m venv /path/to/new/virtual/environment33```3435Выполнение этой команды создаёт целевой каталог (создавая все родительские каталоги, которые ещё не существуют) и помещает в него файл `pyvenv.cfg` с ключом `home`, указывающим на установку Python, из которой была запущена команда. Также создаётся подкаталог `bin` (или `Scripts` в Windows), содержащий копию или символическую ссылку на исполняемый файл Python (в зависимости от платформы или аргументов, указанных при создании окружения). Кроме того, создаётся (изначально пустой) подкаталог `lib/pythonX.Y/site-packages` (в Windows это `Lib\site-packages`). Если указан существующий каталог, он будет использован повторно.3637Устарело с версии 3.6: `pyvenv` был рекомендованным инструментом для создания виртуальных окружений в Python 3.3 и 3.4, и [объявлен устаревшим в Python 3.6](https://python-all.ru/3.7/dev/whatsnew/3.6.html#deprecated-features).3839Изменено в версии 3.5: Теперь для создания виртуальных окружений рекомендуется использовать `venv`.4041В Windows команда `venv` выполняется следующим образом:4243```text44c:\>c:\Python35\python -m venv c:\path\to\myenv45```4647Альтернативно, если вы настроили переменные `PATH` и `PATHEXT` для вашей [установки Python](https://python-all.ru/3.7/using/windows.html#using-on-windows):4849```text50c:\>python -m venv c:\path\to\myenv51```5253При запуске с флагом `-h` команда отображает доступные параметры:5455```text56usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear]57 [--upgrade] [--without-pip] [--prompt PROMPT]58 ENV_DIR [ENV_DIR ...]5960Creates virtual Python environments in one or more target directories.6162positional arguments:63 ENV_DIR A directory to create the environment in.6465optional arguments:66 -h, --help show this help message and exit67 --system-site-packages68 Give the virtual environment access to the system69 site-packages dir.70 --symlinks Try to use symlinks rather than copies, when symlinks71 are not the default for the platform.72 --copies Try to use copies rather than symlinks, even when73 symlinks are the default for the platform.74 --clear Delete the contents of the environment directory if it75 already exists, before environment creation.76 --upgrade Upgrade the environment directory to use this version77 of Python, assuming Python has been upgraded in-place.78 --without-pip Skips installing or upgrading pip in the virtual79 environment (pip is bootstrapped by default)80 --prompt PROMPT Provides an alternative prompt prefix for this81 environment.8283Once an environment has been created, you may wish to activate it, e.g. by84sourcing an activate script in its bin directory.85```8687Изменено в версии 3.4: По умолчанию устанавливается pip, добавлены опции `--without-pip` и `--copies`8889Изменено в версии 3.4: В более ранних версиях, если целевой каталог уже существовал, возникала ошибка, если не была предоставлена опция `--clear` или `--upgrade`.9091> **Примечание**92>93> Хотя символические ссылки поддерживаются в Windows, они не рекомендуются. Особенно важно отметить, что двойной щелчок по `python.exe` в Проводнике разрешит символьную ссылку немедленно и проигнорирует виртуальное окружение.9495Созданный файл `pyvenv.cfg` также включает ключ `include-system-site-packages`, установленный в `true`, если `venv` запущен с опцией `--system-site-packages`, и в `false` в противном случае.9697Если не указана опция `--without-pip`, будет вызван [`ensurepip`](https://python-all.ru/3.7/library/ensurepip.html#module-ensurepip) для начальной установки `pip` в виртуальное окружение.9899Можно указать несколько путей для `venv`, в этом случае будет создано идентичное виртуальное окружение с заданными опциями для каждого указанного пути.100101После создания виртуального окружения его можно «активировать» с помощью скрипта в каталоге исполняемых файлов виртуального окружения. Вызов скрипта зависит от платформы (*\<venv\>* необходимо заменить на путь к каталогу, содержащему виртуальное окружение):102103| Платформа | Оболочка | Команда активации виртуального окружения |104| --- | --- | --- |105| Posix | bash/zsh | $ source \<venv\>/bin/activate |106| | fish | $ . \<venv\>/bin/activate.fish |107| | csh/tcsh | $ source \<venv\>/bin/activate.csh |108| Windows | cmd.exe | C:\\\> \<venv\>\\Scripts\\activate.bat |109| | PowerShell | PS C:\\\> \<venv\>\\Scripts\\Activate.ps1 |110111Активировать окружение *не обязательно*; активация просто добавляет каталог исполняемых файлов виртуального окружения в начало вашего PATH, так что «python» запускает интерпретатор Python из виртуального окружения, и вы можете запускать установленные скрипты без указания полного пути. Однако все скрипты, установленные в виртуальном окружении, должны быть запускаемы без его активации и будут автоматически использовать Python из виртуального окружения.112113Деактивировать виртуальное окружение можно, введя «deactivate» в оболочке. Точный механизм зависит от платформы и является внутренней деталью реализации (обычно используется скрипт или функция оболочки).114115Новое в версии 3.4: `fish` и `csh` скрипты активации.116117> **Примечание**118>119> Виртуальное окружение – это среда Python, в которой интерпретатор Python, библиотеки и скрипты, установленные в неё, изолированы от установленных в других виртуальных окружениях, а также (по умолчанию) от любых библиотек, установленных в «системном» Python, то есть в Python, установленном как часть вашей операционной системы.120>121> Виртуальное окружение – это дерево каталогов, содержащее исполняемые файлы Python и другие файлы, указывающие на то, что это виртуальное окружение.122>123> Распространённые инструменты установки, такие как [setuptools](https://python-all.ru/3.7/library/venv.html) и [pip](https://python-all.ru/3.7/library/venv.html), корректно работают с виртуальными окружениями. Другими словами, когда виртуальное окружение активно, они устанавливают пакеты Python в виртуальное окружение без необходимости явного указания.124>125> Когда виртуальное окружение активно (т.е. запущен интерпретатор Python из виртуального окружения), атрибуты [`sys.prefix`](https://python-all.ru/3.7/library/sys.html#sys.prefix) и [`sys.exec_prefix`](https://python-all.ru/3.7/library/sys.html#sys.exec_prefix) указывают на базовый каталог виртуального окружения, тогда как [`sys.base_prefix`](https://python-all.ru/3.7/library/sys.html#sys.base_prefix) и [`sys.base_exec_prefix`](https://python-all.ru/3.7/library/sys.html#sys.base_exec_prefix) указывают на установку Python вне виртуального окружения, которая использовалась для создания виртуального окружения. Если виртуальное окружение не активно, то [`sys.prefix`](https://python-all.ru/3.7/library/sys.html#sys.prefix) совпадает с [`sys.base_prefix`](https://python-all.ru/3.7/library/sys.html#sys.base_prefix), а [`sys.exec_prefix`](https://python-all.ru/3.7/library/sys.html#sys.exec_prefix) совпадает с [`sys.base_exec_prefix`](https://python-all.ru/3.7/library/sys.html#sys.base_exec_prefix) (все они указывают на установку Python вне виртуального окружения).126>127> Когда виртуальное окружение активно, любые параметры, изменяющие путь установки, будут игнорироваться во всех файлах конфигурации [`distutils`](https://python-all.ru/3.7/library/distutils.html#module-distutils), чтобы предотвратить непреднамеренную установку проектов за пределами виртуального окружения.128>129> При работе в командной оболочке пользователи могут активировать виртуальное окружение, запустив скрипт `activate` в каталоге исполняемых файлов виртуального окружения (точное имя файла и команда для его использования зависят от оболочки), который добавляет каталог исполняемых файлов виртуального окружения в начало переменной окружения `PATH` для текущей оболочки. В других случаях активировать виртуальное окружение не требуется; скрипты, установленные в виртуальные окружения, содержат строку shebang, указывающую на интерпретатор Python из виртуального окружения. Это означает, что скрипт будет выполняться этим интерпретатором независимо от значения `PATH`. В Windows обработка строки shebang поддерживается, если установлен Python Launcher для Windows (это было добавлено в Python 3.3 – см. [**PEP 397**](https://python-all.ru/3.7/library/venv.html) для подробностей). Таким образом, двойной щелчок по установленному скрипту в окне Проводника Windows должен запускать скрипт с правильным интерпретатором без необходимости ссылаться на его виртуальное окружение в `PATH`.130131## API132133Описанный выше высокоуровневый метод использует простой API, предоставляющий механизмы для создателей сторонних виртуальных окружений, чтобы настраивать создание окружения по своему усмотрению – класс [`EnvBuilder`](https://python-all.ru/3.7/library/venv.html#venv.EnvBuilder).134135#### `class venv.EnvBuilder(system_site_packages=False, clear=False, symlinks=False, upgrade=False, with_pip=False, prompt=None)`136137Класс [`EnvBuilder`](https://python-all.ru/3.7/library/venv.html#venv.EnvBuilder) принимает следующие именованные аргументы при создании экземпляра:138139- `system_site_packages` – логическое значение, указывающее, что системные site-packages Python должны быть доступны окружению (по умолчанию `False`).140- `clear` – логическое значение: если истинно, удаляет содержимое любого существующего целевого каталога перед созданием окружения.141- `symlinks` – логическое значение, указывающее, следует ли пытаться создать символическую ссылку на бинарный файл Python вместо копирования.142- `upgrade` – логическое значение: если истинно, обновляет существующее окружение с текущим Python – для использования, когда этот Python был обновлен на месте (по умолчанию `False`).143- `with_pip` – логическое значение: если истинно, гарантирует установку pip в виртуальное окружение. Для этого используется [`ensurepip`](https://python-all.ru/3.7/library/ensurepip.html#module-ensurepip) с опцией `--default-pip`.144- `prompt` – строка, используемая после активации виртуального окружения (по умолчанию равна `None`, то есть будет использовано имя каталога окружения).145146Изменено в версии 3.4: Добавлен параметр `with_pip`147148Новое в версии 3.6: Добавлен параметр `prompt`149150Создатели сторонних инструментов для виртуальных окружений могут свободно использовать предоставленный класс [`EnvBuilder`](https://python-all.ru/3.7/library/venv.html#venv.EnvBuilder) в качестве базового класса.151152Возвращаемый env-builder – это объект, у которого есть метод `create`:153154#### `create(env_dir)`155156Создаёт виртуальное окружение путём указания целевого каталога (абсолютного или относительного по отношению к текущему каталогу), который будет содержать виртуальное окружение. Метод `create` либо создаст окружение в указанном каталоге, либо вызовет соответствующее исключение.157158Метод `create` класса [`EnvBuilder`](https://python-all.ru/3.7/library/venv.html#venv.EnvBuilder) иллюстрирует точки расширения, доступные для настройки в подклассах:159160```python161def create(self, env_dir):162 """163 Создаёт виртуализированное окружение Python в указанном каталоге.164 Параметр env_dir – это целевой каталог, в котором создаётся окружение.165 """166 env_dir = os.path.abspath(env_dir)167 context = self.ensure_directories(env_dir)168 self.create_configuration(context)169 self.setup_python(context)170 self.setup_scripts(context)171 self.post_setup(context)172```173174Каждый из методов [`ensure_directories()`](https://python-all.ru/3.7/library/venv.html#venv.EnvBuilder.ensure_directories), [`create_configuration()`](https://python-all.ru/3.7/library/venv.html#venv.EnvBuilder.create_configuration), [`setup_python()`](https://python-all.ru/3.7/library/venv.html#venv.EnvBuilder.setup_python), [`setup_scripts()`](https://python-all.ru/3.7/library/venv.html#venv.EnvBuilder.setup_scripts) и [`post_setup()`](https://python-all.ru/3.7/library/venv.html#venv.EnvBuilder.post_setup) может быть переопределён.175176#### `ensure_directories(env_dir)`177178Создаёт каталог окружения и все необходимые каталоги, а затем возвращает объект контекста. Это просто контейнер для атрибутов (например, путей), используемый другими методами. Каталоги могут уже существовать, при условии, что были указаны `clear` или `upgrade`, чтобы разрешить работу с существующим каталогом окружения.179180#### `create_configuration(context)`181182Создаёт файл конфигурации `pyvenv.cfg` в окружении.183184#### `setup_python(context)`185186Создаёт копию или символическую ссылку на исполняемый файл Python в окружении. В системах POSIX, если был указан конкретный исполняемый файл `python3.x`, будут созданы символические ссылки на `python` и `python3`, указывающие на этот исполняемый файл, если файлы с такими именами уже не существуют.187188#### `setup_scripts(context)`189190Устанавливает скрипты активации, соответствующие платформе, в виртуальное окружение.191192#### `post_setup(context)`193194Метод-заглушка, который может быть переопределён в сторонних реализациях для предварительной установки пакетов в виртуальное окружение или выполнения других действий после создания.195196Изменено в версии 3.7.2: В Windows теперь используются скрипты-перенаправители для `python[w].exe` вместо копирования самих исполняемых файлов. В версии 3.7.2 только [`setup_python()`](https://python-all.ru/3.7/library/venv.html#venv.EnvBuilder.setup_python) ничего не делает, если не запущен из сборки в исходном дереве.197198Изменено в версии 3.7.3: В Windows скрипты-перенаправители копируются как часть [`setup_python()`](https://python-all.ru/3.7/library/venv.html#venv.EnvBuilder.setup_python) вместо [`setup_scripts()`](https://python-all.ru/3.7/library/venv.html#venv.EnvBuilder.setup_scripts). В версии 3.7.2 это было не так. При использовании символьных ссылок будут связаны исходные исполняемые файлы.199200Кроме того, [`EnvBuilder`](https://python-all.ru/3.7/library/venv.html#venv.EnvBuilder) предоставляет этот вспомогательный метод, который можно вызвать из [`setup_scripts()`](https://python-all.ru/3.7/library/venv.html#venv.EnvBuilder.setup_scripts) или [`post_setup()`](https://python-all.ru/3.7/library/venv.html#venv.EnvBuilder.post_setup) в подклассах для установки пользовательских скриптов в виртуальное окружение.201202#### `install_scripts(context, path)`203204*path* – это путь к каталогу, который должен содержать подкаталоги «common», «posix», «nt», каждый из которых содержит скрипты, предназначенные для каталога bin в окружении. Содержимое «common» и каталога, соответствующего [`os.name`](https://python-all.ru/3.7/library/os.html#os.name), копируется после замены некоторых текстовых плейсхолдеров:205206- `__VENV_DIR__` заменяется на абсолютный путь к каталогу окружения.207- `__VENV_NAME__` заменяется на имя окружения (последний сегмент пути к каталогу окружения).208- `__VENV_PROMPT__` заменяется на приглашение (имя окружения в скобках и с последующим пробелом)209- `__VENV_BIN_NAME__` заменяется на имя каталога bin ( `bin` или `Scripts`).210- `__VENV_PYTHON__` заменяется на абсолютный путь к исполняемому файлу окружения.211212Каталоги могут существовать (на случай, когда обновляется существующее окружение).213214Также существует удобная функция уровня модуля:215216#### `venv.create(env_dir, system_site_packages=False, clear=False, symlinks=False, with_pip=False, prompt=None)`217218Создаёт экземпляр [`EnvBuilder`](https://python-all.ru/3.7/library/venv.html#venv.EnvBuilder) с заданными именованными аргументами и вызывает его метод [`create()`](https://python-all.ru/3.7/library/venv.html#venv.EnvBuilder.create) с аргументом *env\_dir*.219220Новое в версии 3.3.221222Изменено в версии 3.4: Добавлен параметр `with_pip`223224Изменено в версии 3.6: Добавлен параметр `prompt`225226## Пример расширения `EnvBuilder`227228Следующий скрипт показывает, как расширить [`EnvBuilder`](https://python-all.ru/3.7/library/venv.html#venv.EnvBuilder), реализовав подкласс, который устанавливает setuptools и pip в созданное виртуальное окружение:229230```python231import os232import os.path233from subprocess import Popen, PIPE234import sys235from threading import Thread236from urllib.parse import urlparse237from urllib.request import urlretrieve238import venv239240class ExtendedEnvBuilder(venv.EnvBuilder):241 """242 Данный построитель устанавливает setuptools и pip, чтобы с их помощью можно было243 устанавливать другие пакеты в созданное виртуальное окружение командой pip или easy_install.244245 :param nodist: Если истина, setuptools и pip не устанавливаются в246 созданное виртуальное окружение.247 :param nopip: Если истина, pip не устанавливается в созданное248 виртуальное окружение.249 :param progress: Если setuptools или pip устанавливаются, за ходом установки250 можно следить, передав вызываемый объект для отслеживания прогресса.251 Если он указан, то вызывается с двумя252 аргументами: строкой, описывающей текущий этап, и253 контекстом, указывающим, откуда пришла эта строка.254 Аргумент context может принимать одно из трёх значений:255 'main' – вызов происходит из самой virtualize(),256 а также 'stdout' и 'stderr' – строки берутся257 из потоков вывода подпроцесса, который258 используется для установки приложения.259260 Если вызываемый объект не указан, по умолчанию сведения о ходе выполнения261 выводятся в sys.stderr.262 """263264 def __init__(self, *args, **kwargs):265 self.nodist = kwargs.pop('nodist', False)266 self.nopip = kwargs.pop('nopip', False)267 self.progress = kwargs.pop('progress', None)268 self.verbose = kwargs.pop('verbose', False)269 super().__init__(*args, **kwargs)270271 def post_setup(self, context):272 """273 Устанавливает пакеты, которые необходимо предварительно установить в создаваемое виртуальное окружение.274 создаваемое виртуальное окружение275276 обрабатываемого запроса на создание виртуального окружения277 запрос на создание обрабатывается278 """279 os.environ['VIRTUAL_ENV'] = context.env_dir280 if not self.nodist:281 self.install_setuptools(context)282 # Читает строки из потока вывода подпроцесса и либо передаёт их вызываемому объекту для отслеживания хода выполнения283 if not self.nopip and not self.nodist:284 self.install_pip(context)285286 def reader(self, stream, context):287 """288 Читает строки из потока вывода подпроцесса и передаёт их в индикатор прогресса289 Загружает скрипт в папку с бинарными файлами виртуального окружения290 """291 progress = self.progress292 while True:293 s = stream.readline()294 if not s:295 break296 if progress is not None:297 progress(s, context)298 else:299 if not self.verbose:300 sys.stderr.write('.')301 else:302 sys.stderr.write(s.decode('utf-8'))303 sys.stderr.flush()304 stream.close()305306 def install_script(self, context, name, url):307 _, _, path, _, _, _ = urlparse(url)308 fn = os.path.split(path)[-1]309 binpath = context.bin_path310 distpath = os.path.join(binpath, fn)311 # Устанавливает в виртуальное окружение312 urlretrieve(url, distpath)313 progress = self.progress314 if self.verbose:315 term = '\n'316 else:317 term = ''318 if progress is not None:319 progress('Installing %s ...%s' % (name, term), 'main')320 else:321 sys.stderr.write('Installing %s ...%s' % (name, term))322 sys.stderr.flush()323 # Очистка – больше не требуется324 args = [context.env_exe, fn]325 p = Popen(args, stdout=PIPE, stderr=PIPE, cwd=binpath)326 t1 = Thread(target=self.reader, args=(p.stdout, 'stdout'))327 t1.start()328 t2 = Thread(target=self.reader, args=(p.stderr, 'stderr'))329 t2.start()330 p.wait()331 t1.join()332 t2.join()333 if progress is not None:334 progress('done.', 'main')335 else:336 sys.stderr.write('done.\n')337 # Очищает – больше не требуется338 os.unlink(distpath)339340 def install_setuptools(self, context):341 """342 Устанавливает setuptools в виртуальное окружение343344 обрабатываемого запроса на создание виртуального окружения345 запрос на создание обрабатывается346 """347 url = 'https://bitbucket.org/pypa/setuptools/downloads/ez_setup.py'348 self.install_script(context, 'setuptools', url)349 # Устанавливает pip в виртуальное окружение.350 pred = lambda o: o.startswith('setuptools-') and o.endswith('.tar.gz')351 files = filter(pred, os.listdir(context.bin_path))352 for f in files:353 f = os.path.join(context.bin_path, f)354 os.unlink(f)355356 def install_pip(self, context):357 """358 Устанавливает pip в виртуальное окружение359360 обрабатываемого запроса на создание виртуального окружения361 запрос на создание обрабатывается362 """363 url = 'https://raw.github.com/pypa/pip/master/contrib/get-pip.py'364 self.install_script(context, 'pip', url)365366def main(args=None):367 compatible = True368 if sys.version_info < (3, 3):369 compatible = False370 elif not hasattr(sys, 'base_prefix'):371 compatible = False372 if not compatible:373 raise ValueError('This script is only for use with '374 'Python 3.3 or later')375 else:376 import argparse377378 parser = argparse.ArgumentParser(prog=__name__,379 description='Creates virtual Python '380 'environments in one or '381 'more target '382 'directories.')383 parser.add_argument('dirs', metavar='ENV_DIR', nargs='+',384 help='A directory in which to create the385 'virtual environment.')386 parser.add_argument('--no-setuptools', default=False,387 action='store_true', dest='nodist',388 help="Don't install setuptools or pip in the "389 "virtual environment.")390 parser.add_argument('--no-pip', default=False,391 action='store_true', dest='nopip',392 help="Don't install pip in the virtual "393 "environment.")394 parser.add_argument('--system-site-packages', default=False,395 action='store_true', dest='system_site',396 help='Give the virtual environment access to the '397 'system site-packages dir.')398 if os.name == 'nt':399 use_symlinks = False400 else:401 use_symlinks = True402 parser.add_argument('--symlinks', default=use_symlinks,403 action='store_true', dest='symlinks',404 help='Try to use symlinks rather than copies, '405 'when symlinks are not the default for '406 'the platform.')407 parser.add_argument('--clear', default=False, action='store_true',408 dest='clear', help='Delete the contents of the '409 'virtual environment '410 'directory if it already '411 'exists, before virtual '412 'environment creation.')413 parser.add_argument('--upgrade', default=False, action='store_true',414 dest='upgrade', help='Upgrade the virtual '415 'environment directory to '416 'use this version of '417 'Python, assuming Python '418 'has been upgraded '419 'in-place.')420 parser.add_argument('--verbose', default=False, action='store_true',421 dest='verbose', help='Display the output '422 'from the scripts which '423 'install setuptools and pip.')424 options = parser.parse_args(args)425 if options.upgrade and options.clear:426 raise ValueError('you cannot supply --upgrade and --clear together.')427 builder = ExtendedEnvBuilder(system_site_packages=options.system_site,428 clear=options.clear,429 symlinks=options.symlinks,430 upgrade=options.upgrade,431 nodist=options.nodist,432 nopip=options.nopip,433 verbose=options.verbose)434 for d in options.dirs:435 builder.create(d)436437if __name__ == '__main__':438 rc = 1439 try:440 main()441 rc = 0442 except Exception as e:443 print('Error: %s' % e, file=sys.stderr)444 sys.exit(rc)445```446447Этот скрипт также доступен для загрузки [онлайн](https://python-all.ru/3.7/library/venv.html).448