venv.md
1> **Источник:** https://python-all.ru/3.6/library/venv.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 28.3. [`venv`](https://python-all.ru/3.6/library/venv.html#module-venv) – Создание виртуальных окружений89Новое в версии 3.3.1011**Исходный код:** [Lib/venv/](https://python-all.ru/src/3.6/Lib/venv)1213---1415Модуль [`venv`](https://python-all.ru/3.6/library/venv.html#module-venv) предоставляет поддержку для создания легковесных «виртуальных окружений» с собственными site-каталогами, опционально изолированными от системных site-каталогов. Каждое виртуальное окружение имеет собственный бинарный файл Python (что позволяет создавать окружения с разными версиями Python) и может иметь свой независимый набор установленных пакетов Python в своих site-каталогах.1617За дополнительной информацией о виртуальных окружениях Python обращайтесь к [**PEP 405**](https://python-all.ru/3.6/library/venv.html).1819> **Примечание**20>21> Скрипт `pyvenv` устарел начиная с Python 3.6 в пользу использования `python3 -m venv`, чтобы предотвратить возможную путаницу относительно того, на каком интерпретаторе Python будет основано виртуальное окружение.2223## 28.3.1. Создание виртуальных окружений2425Создание [виртуальных окружений](https://python-all.ru/3.6/library/venv.html#venv-def) выполняется с помощью команды `venv`:2627```python28python3 -m venv /path/to/new/virtual/environment29```3031Выполнение этой команды создаёт целевой каталог (создавая все родительские каталоги, которые ещё не существуют) и помещает в него файл `pyvenv.cfg` с ключом `home`, указывающим на установку Python, из которой была запущена команда. Также создаётся подкаталог `bin` (или `Scripts` в Windows), содержащий копию или символическую ссылку на исполняемый файл Python (в зависимости от платформы или аргументов, указанных при создании окружения). Кроме того, создаётся (изначально пустой) подкаталог `lib/pythonX.Y/site-packages` (в Windows это `Lib\site-packages`). Если указан существующий каталог, он будет использован повторно.3233Устарело с версии 3.6: `pyvenv` был рекомендованным инструментом для создания виртуальных окружений в Python 3.3 и 3.4, и [объявлен устаревшим в Python 3.6](https://python-all.ru/3.6/dev/whatsnew/3.6.html#deprecated-features).3435Изменено в версии 3.5: Теперь для создания виртуальных окружений рекомендуется использовать `venv`.3637> **См. также**38>39> [Руководство пользователя по упаковке Python: создание и использование виртуальных окружений](https://python-all.ru/3.6/library/venv.html)4041В Windows команда `venv` выполняется следующим образом:4243```text44c:\>c:\Python35\python -m venv c:\path\to\myenv45```4647Альтернативно, если вы настроили переменные `PATH` и `PATHEXT` для вашей [установки Python](https://python-all.ru/3.6/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]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)8081Once an environment has been created, you may wish to activate it, e.g. by82sourcing an activate script in its bin directory.83```8485Изменено в версии 3.4: По умолчанию устанавливается pip, добавлены опции `--without-pip` и `--copies`8687Изменено в версии 3.4: В более ранних версиях, если целевой каталог уже существовал, возникала ошибка, если не была предоставлена опция `--clear` или `--upgrade`.8889Созданный файл `pyvenv.cfg` также включает ключ `include-system-site-packages`, установленный в `true`, если `venv` запущен с опцией `--system-site-packages`, и в `false` в противном случае.9091Если не указана опция `--without-pip`, будет вызван [`ensurepip`](https://python-all.ru/3.6/library/ensurepip.html#module-ensurepip) для начальной установки `pip` в виртуальное окружение.9293Можно указать несколько путей для `venv`, в этом случае будет создано идентичное виртуальное окружение с заданными опциями для каждого указанного пути.9495После создания виртуального окружения его можно «активировать» с помощью скрипта в каталоге исполняемых файлов виртуального окружения. Вызов скрипта зависит от платформы (*\<venv\>* необходимо заменить на путь к каталогу, содержащему виртуальное окружение):9697| Платформа | Оболочка | Команда активации виртуального окружения |98| --- | --- | --- |99| Posix | bash/zsh | $ source \<venv\>/bin/activate |100| | fish | $ . \<venv\>/bin/activate.fish |101| | csh/tcsh | $ source \<venv\>/bin/activate.csh |102| Windows | cmd.exe | C:\\\> \<venv\>\\Scripts\\activate.bat |103| | PowerShell | PS C:\\\> \<venv\>\\Scripts\\Activate.ps1 |104105Активировать окружение *не обязательно*; активация просто добавляет каталог исполняемых файлов виртуального окружения в начало вашего PATH, так что «python» запускает интерпретатор Python из виртуального окружения, и вы можете запускать установленные скрипты без указания полного пути. Однако все скрипты, установленные в виртуальном окружении, должны быть запускаемы без его активации и будут автоматически использовать Python из виртуального окружения.106107Деактивировать виртуальное окружение можно, введя «deactivate» в оболочке. Точный механизм зависит от платформы: например, скрипт активации Bash определяет функцию «deactivate», тогда как в Windows существуют отдельные скрипты `deactivate.bat` и `Deactivate.ps1`, которые устанавливаются при создании виртуального окружения.108109Новое в версии 3.4: `fish` и `csh` скрипты активации.110111> **Примечание**112>113> Виртуальное окружение – это среда Python, в которой интерпретатор Python, библиотеки и скрипты, установленные в неё, изолированы от установленных в других виртуальных окружениях, а также (по умолчанию) от любых библиотек, установленных в «системном» Python, то есть в Python, установленном как часть вашей операционной системы.114>115> Виртуальное окружение – это дерево каталогов, содержащее исполняемые файлы Python и другие файлы, указывающие на то, что это виртуальное окружение.116>117> Обычные инструменты установки, такие как `Setuptools` и `pip`, работают с виртуальными окружениями как ожидается. Другими словами, когда виртуальное окружение активно, они устанавливают пакеты Python в виртуальное окружение без необходимости явного указания.118>119> Когда виртуальное окружение активно (т.е. запущен интерпретатор Python из виртуального окружения), атрибуты [`sys.prefix`](https://python-all.ru/3.6/library/sys.html#sys.prefix) и [`sys.exec_prefix`](https://python-all.ru/3.6/library/sys.html#sys.exec_prefix) указывают на базовый каталог виртуального окружения, тогда как [`sys.base_prefix`](https://python-all.ru/3.6/library/sys.html#sys.base_prefix) и [`sys.base_exec_prefix`](https://python-all.ru/3.6/library/sys.html#sys.base_exec_prefix) указывают на установку Python вне виртуального окружения, которая использовалась для создания виртуального окружения. Если виртуальное окружение не активно, то [`sys.prefix`](https://python-all.ru/3.6/library/sys.html#sys.prefix) совпадает с [`sys.base_prefix`](https://python-all.ru/3.6/library/sys.html#sys.base_prefix), а [`sys.exec_prefix`](https://python-all.ru/3.6/library/sys.html#sys.exec_prefix) совпадает с [`sys.base_exec_prefix`](https://python-all.ru/3.6/library/sys.html#sys.base_exec_prefix) (все они указывают на установку Python вне виртуального окружения).120>121> Когда виртуальное окружение активно, любые параметры, изменяющие путь установки, будут игнорироваться во всех файлах конфигурации distutils, чтобы предотвратить случайную установку проектов за пределами виртуального окружения.122>123> При работе в командной оболочке пользователи могут активировать виртуальное окружение, запустив скрипт `activate` в каталоге исполняемых файлов виртуального окружения (точное имя файла зависит от оболочки), который добавляет каталог исполняемых файлов виртуального окружения в переменную окружения `PATH` для текущей оболочки. В других обстоятельствах активировать виртуальное окружение не требуется – скрипты, установленные в виртуальное окружение, имеют строку shebang, указывающую на интерпретатор Python виртуального окружения. Это означает, что скрипт будет выполняться этим интерпретатором независимо от значения `PATH`. В Windows обработка shebang-строк поддерживается, если установлен Python Launcher for Windows (эта возможность была добавлена в Python 3.3 – см. [**PEP 397**](https://python-all.ru/3.6/library/venv.html) для подробностей). Таким образом, двойной щелчок по установленному скрипту в окне Проводника Windows должен запустить его с правильным интерпретатором без необходимости ссылаться на его виртуальное окружение в `PATH`.124125## 28.3.2. API126127Описанный выше высокоуровневый метод использует простой API, предоставляющий механизмы для создателей сторонних виртуальных окружений, чтобы настраивать создание окружения по своему усмотрению – класс [`EnvBuilder`](https://python-all.ru/3.6/library/venv.html#venv.EnvBuilder).128129#### `class venv.EnvBuilder(system_site_packages=False, clear=False, symlinks=False, upgrade=False, with_pip=False, prompt=None)`130131Класс [`EnvBuilder`](https://python-all.ru/3.6/library/venv.html#venv.EnvBuilder) принимает следующие именованные аргументы при создании экземпляра:132133- `system_site_packages` – логическое значение, указывающее, что системные site-packages Python должны быть доступны окружению (по умолчанию `False`).134- `clear` – логическое значение: если истинно, удаляет содержимое любого существующего целевого каталога перед созданием окружения.135- `symlinks` – логическое значение, указывающее, следует ли пытаться создать симлинк на бинарный файл Python (и любые необходимые DLL или другие бинарные файлы, например `pythonw.exe`) вместо копирования.136- `upgrade` – логическое значение: если истинно, обновляет существующее окружение с текущим Python – для использования, когда этот Python был обновлен на месте (по умолчанию `False`).137- `with_pip` – логическое значение: если истинно, гарантирует установку pip в виртуальное окружение. Для этого используется [`ensurepip`](https://python-all.ru/3.6/library/ensurepip.html#module-ensurepip) с опцией `--default-pip`.138- `prompt` – строка, используемая после активации виртуального окружения (по умолчанию равна `None`, то есть будет использовано имя каталога окружения).139140Изменено в версии 3.4: Добавлен параметр `with_pip`141142Новое в версии 3.6: Добавлен параметр `prompt`143144Создатели сторонних инструментов для виртуальных окружений могут свободно использовать предоставленный класс `EnvBuilder` в качестве базового класса.145146Возвращаемый env-builder – это объект, у которого есть метод `create`:147148#### `create(env_dir)`149150Этот метод принимает в качестве обязательного аргумента путь (абсолютный или относительный к текущему каталогу) целевого каталога, который должен содержать виртуальное окружение. Метод `create` либо создаст окружение в указанном каталоге, либо вызовет соответствующее исключение.151152Метод `create` класса `EnvBuilder` иллюстрирует хуки, доступные для настройки подклассов:153154```python155def create(self, env_dir):156 """157 Создаёт виртуализированное окружение Python в указанном каталоге.158 Параметр env_dir – это целевой каталог, в котором создаётся окружение.159 """160 env_dir = os.path.abspath(env_dir)161 context = self.ensure_directories(env_dir)162 self.create_configuration(context)163 self.setup_python(context)164 self.setup_scripts(context)165 self.post_setup(context)166```167168Каждый из методов [`ensure_directories()`](https://python-all.ru/3.6/library/venv.html#venv.EnvBuilder.ensure_directories), [`create_configuration()`](https://python-all.ru/3.6/library/venv.html#venv.EnvBuilder.create_configuration), [`setup_python()`](https://python-all.ru/3.6/library/venv.html#venv.EnvBuilder.setup_python), [`setup_scripts()`](https://python-all.ru/3.6/library/venv.html#venv.EnvBuilder.setup_scripts) и [`post_setup()`](https://python-all.ru/3.6/library/venv.html#venv.EnvBuilder.post_setup) может быть переопределён.169170#### `ensure_directories(env_dir)`171172Создаёт каталог окружения и все необходимые каталоги, а затем возвращает объект контекста. Это просто контейнер для атрибутов (например, путей), используемый другими методами. Каталоги могут уже существовать, при условии, что были указаны `clear` или `upgrade`, чтобы разрешить работу с существующим каталогом окружения.173174#### `create_configuration(context)`175176Создаёт файл конфигурации `pyvenv.cfg` в окружении.177178#### `setup_python(context)`179180Создает копию исполняемого файла Python (а в Windows – DLL) в окружении. В POSIX-системе, если был использован конкретный исполняемый файл `python3.x`, будут созданы симлинки на `python` и `python3`, указывающие на этот исполняемый файл, если файлы с такими именами уже не существуют.181182#### `setup_scripts(context)`183184Устанавливает скрипты активации, соответствующие платформе, в виртуальное окружение.185186#### `post_setup(context)`187188Метод-заглушка, который может быть переопределён в сторонних реализациях для предварительной установки пакетов в виртуальное окружение или выполнения других действий после создания.189190Кроме того, [`EnvBuilder`](https://python-all.ru/3.6/library/venv.html#venv.EnvBuilder) предоставляет этот вспомогательный метод, который можно вызвать из [`setup_scripts()`](https://python-all.ru/3.6/library/venv.html#venv.EnvBuilder.setup_scripts) или [`post_setup()`](https://python-all.ru/3.6/library/venv.html#venv.EnvBuilder.post_setup) в подклассах для установки пользовательских скриптов в виртуальное окружение.191192#### `install_scripts(context, path)`193194*path* – это путь к каталогу, который должен содержать подкаталоги «common», «posix», «nt», каждый из которых содержит скрипты, предназначенные для каталога bin в окружении. Содержимое «common» и каталога, соответствующего [`os.name`](https://python-all.ru/3.6/library/os.html#os.name), копируется после замены некоторых текстовых плейсхолдеров:195196- `__VENV_DIR__` заменяется на абсолютный путь к каталогу окружения.197- `__VENV_NAME__` заменяется на имя окружения (последний сегмент пути к каталогу окружения).198- `__VENV_PROMPT__` заменяется на приглашение (имя окружения в скобках и с последующим пробелом)199- `__VENV_BIN_NAME__` заменяется на имя каталога bin ( `bin` или `Scripts`).200- `__VENV_PYTHON__` заменяется на абсолютный путь к исполняемому файлу окружения.201202Каталоги могут существовать (на случай, когда обновляется существующее окружение).203204Также существует удобная функция уровня модуля:205206#### `venv.create(env_dir, system_site_packages=False, clear=False, symlinks=False, with_pip=False)`207208Создаёт экземпляр [`EnvBuilder`](https://python-all.ru/3.6/library/venv.html#venv.EnvBuilder) с заданными именованными аргументами и вызывает его метод [`create()`](https://python-all.ru/3.6/library/venv.html#venv.EnvBuilder.create) с аргументом *env\_dir*.209210Изменено в версии 3.4: Добавлен параметр `with_pip`211212## 28.3.3. Пример расширения `EnvBuilder`213214Следующий скрипт показывает, как расширить [`EnvBuilder`](https://python-all.ru/3.6/library/venv.html#venv.EnvBuilder), реализовав подкласс, который устанавливает setuptools и pip в созданное виртуальное окружение:215216```python217import os218import os.path219from subprocess import Popen, PIPE220import sys221from threading import Thread222from urllib.parse import urlparse223from urllib.request import urlretrieve224import venv225226class ExtendedEnvBuilder(venv.EnvBuilder):227 """228 Данный построитель устанавливает setuptools и pip, чтобы с их помощью можно было229 устанавливать другие пакеты в созданное виртуальное окружение командой pip или easy_install.230231 :param nodist: Если True, setuptools и pip не устанавливаются в232 созданное виртуальное окружение.233 :param nopip: Если True, pip не устанавливается в создаваемое234 виртуальное окружение.235 :param progress: Если setuptools или pip устанавливаются, за ходом установки236 можно следить, передав вызываемый объект для отслеживания прогресса.237 Если он указан, то вызывается с двумя238 аргументами: строкой, описывающей текущий этап, и239 контекстом, указывающим, откуда пришла эта строка.240 Аргумент context может принимать одно из трёх значений:241 'main' – вызов происходит из самой virtualize(),242 а также 'stdout' и 'stderr' – строки берутся243 из потоков вывода подпроцесса, который244 используется для установки приложения.245246 Если вызываемый объект не указан, по умолчанию сведения о ходе выполнения247 выводятся в sys.stderr.248 """249250 def __init__(self, *args, **kwargs):251 self.nodist = kwargs.pop('nodist', False)252 self.nopip = kwargs.pop('nopip', False)253 self.progress = kwargs.pop('progress', None)254 self.verbose = kwargs.pop('verbose', False)255 super().__init__(*args, **kwargs)256257 def post_setup(self, context):258 """259 Устанавливает пакеты, которые необходимо предварительно установить в создаваемое виртуальное окружение.260 создаваемое виртуальное окружение261262 обрабатываемого запроса на создание виртуального окружения263 запрос на создание обрабатывается264 """265 os.environ['VIRTUAL_ENV'] = context.env_dir266 if not self.nodist:267 self.install_setuptools(context)268 # Читает строки из потока вывода подпроцесса и либо передаёт их вызываемому объекту для отслеживания хода выполнения269 if not self.nopip and not self.nodist:270 self.install_pip(context)271272 def reader(self, stream, context):273 """274 Читает строки из потока вывода подпроцесса и передаёт их в индикатор прогресса275 Загружает скрипт в папку с бинарными файлами виртуального окружения276 """277 progress = self.progress278 while True:279 s = stream.readline()280 if not s:281 break282 if progress is not None:283 progress(s, context)284 else:285 if not self.verbose:286 sys.stderr.write('.')287 else:288 sys.stderr.write(s.decode('utf-8'))289 sys.stderr.flush()290 stream.close()291292 def install_script(self, context, name, url):293 _, _, path, _, _, _ = urlparse(url)294 fn = os.path.split(path)[-1]295 binpath = context.bin_path296 distpath = os.path.join(binpath, fn)297 # Устанавливает в виртуальное окружение298 urlretrieve(url, distpath)299 progress = self.progress300 if self.verbose:301 term = '\n'302 else:303 term = ''304 if progress is not None:305 progress('Installing %s ...%s' % (name, term), 'main')306 else:307 sys.stderr.write('Installing %s ...%s' % (name, term))308 sys.stderr.flush()309 # Очистка – больше не требуется310 args = [context.env_exe, fn]311 p = Popen(args, stdout=PIPE, stderr=PIPE, cwd=binpath)312 t1 = Thread(target=self.reader, args=(p.stdout, 'stdout'))313 t1.start()314 t2 = Thread(target=self.reader, args=(p.stderr, 'stderr'))315 t2.start()316 p.wait()317 t1.join()318 t2.join()319 if progress is not None:320 progress('done.', 'main')321 else:322 sys.stderr.write('done.\n')323 # Очищает – больше не требуется324 os.unlink(distpath)325326 def install_setuptools(self, context):327 """328 Устанавливает setuptools в виртуальное окружение329330 обрабатываемого запроса на создание виртуального окружения331 запрос на создание обрабатывается332 """333 url = 'https://bitbucket.org/pypa/setuptools/downloads/ez_setup.py'334 self.install_script(context, 'setuptools', url)335 # Устанавливает pip в виртуальное окружение.336 pred = lambda o: o.startswith('setuptools-') and o.endswith('.tar.gz')337 files = filter(pred, os.listdir(context.bin_path))338 for f in files:339 f = os.path.join(context.bin_path, f)340 os.unlink(f)341342 def install_pip(self, context):343 """344 Устанавливает pip в виртуальное окружение345346 обрабатываемого запроса на создание виртуального окружения347 запрос на создание обрабатывается348 """349 url = 'https://raw.github.com/pypa/pip/master/contrib/get-pip.py'350 self.install_script(context, 'pip', url)351352def main(args=None):353 compatible = True354 if sys.version_info < (3, 3):355 compatible = False356 elif not hasattr(sys, 'base_prefix'):357 compatible = False358 if not compatible:359 raise ValueError('This script is only for use with '360 'Python 3.3 or later')361 else:362 import argparse363364 parser = argparse.ArgumentParser(prog=__name__,365 description='Creates virtual Python '366 'environments in one or '367 'more target '368 'directories.')369 parser.add_argument('dirs', metavar='ENV_DIR', nargs='+',370 help='A directory in which to create the371 'virtual environment.')372 parser.add_argument('--no-setuptools', default=False,373 action='store_true', dest='nodist',374 help="Don't install setuptools or pip in the "375 "virtual environment.")376 parser.add_argument('--no-pip', default=False,377 action='store_true', dest='nopip',378 help="Don't install pip in the virtual "379 "environment.")380 parser.add_argument('--system-site-packages', default=False,381 action='store_true', dest='system_site',382 help='Give the virtual environment access to the '383 'system site-packages dir.')384 if os.name == 'nt':385 use_symlinks = False386 else:387 use_symlinks = True388 parser.add_argument('--symlinks', default=use_symlinks,389 action='store_true', dest='symlinks',390 help='Try to use symlinks rather than copies, '391 'when symlinks are not the default for '392 'the platform.')393 parser.add_argument('--clear', default=False, action='store_true',394 dest='clear', help='Delete the contents of the '395 'virtual environment '396 'directory if it already '397 'exists, before virtual '398 'environment creation.')399 parser.add_argument('--upgrade', default=False, action='store_true',400 dest='upgrade', help='Upgrade the virtual '401 'environment directory to '402 'use this version of '403 'Python, assuming Python '404 'has been upgraded '405 'in-place.')406 parser.add_argument('--verbose', default=False, action='store_true',407 dest='verbose', help='Display the output '408 'from the scripts which '409 'install setuptools and pip.')410 options = parser.parse_args(args)411 if options.upgrade and options.clear:412 raise ValueError('you cannot supply --upgrade and --clear together.')413 builder = ExtendedEnvBuilder(system_site_packages=options.system_site,414 clear=options.clear,415 symlinks=options.symlinks,416 upgrade=options.upgrade,417 nodist=options.nodist,418 nopip=options.nopip,419 verbose=options.verbose)420 for d in options.dirs:421 builder.create(d)422423if __name__ == '__main__':424 rc = 1425 try:426 main()427 rc = 0428 except Exception as e:429 print('Error: %s' % e, file=sys.stderr)430 sys.exit(rc)431```432433Этот скрипт также доступен для загрузки [онлайн](https://python-all.ru/3.6/library/venv.html).434