venv.md
1> **Источник:** https://python-all.ru/3.5/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.5/library/venv.html#module-venv) – Создание виртуальных окружений89Новое в версии 3.3.1011**Исходный код:** [Lib/venv/](https://python-all.ru/src/3.5/Lib/venv)1213---1415Модуль [`venv`](https://python-all.ru/3.5/library/venv.html#module-venv) предоставляет поддержку для создания легковесных «виртуальных окружений» с собственными site-каталогами, опционально изолированными от системных site-каталогов. Каждое виртуальное окружение имеет собственный бинарный файл Python (что позволяет создавать окружения с разными версиями Python) и может иметь свой независимый набор установленных пакетов Python в своих site-каталогах.1617За дополнительной информацией о виртуальных окружениях Python обращайтесь к [**PEP 405**](https://python-all.ru/3.5/library/venv.html).1819> **Примечание**20>21> Скрипт `pyvenv` устарел начиная с Python 3.6 в пользу использования `python3 -m venv`, чтобы предотвратить возможную путаницу относительно того, на каком интерпретаторе Python будет основано виртуальное окружение.2223## 28.3.1. Создание виртуальных окружений2425Создание [виртуальных окружений](https://python-all.ru/3.5/library/venv.html#venv-def) выполняется запуском скрипта `pyvenv`:2627```python28pyvenv /path/to/new/virtual/environment29```3031Running this command creates the target directory (creating any parent directories that don’t exist already) and places a `pyvenv.cfg` file in it with a `home` key pointing to the Python installation the command was run from. It also creates a `bin` (or `Scripts` on Windows) subdirectory containing a copy of the `python` binary (or binaries, in the case of Windows). It also creates an (initially empty) `lib/pythonX.Y/site-packages` subdirectory (on Windows, this is `Lib\site-packages`).3233> **См. также**34>35> [Руководство пользователя по упаковке Python: создание и использование виртуальных окружений](https://python-all.ru/3.5/library/venv.html)3637В Windows, возможно, придётся вызвать скрипт `pyvenv` следующим образом, если отсутствуют соответствующие настройки PATH и PATHEXT:3839```text40c:\Temp>c:\Python35\python c:\Python35\Tools\Scripts\pyvenv.py myenv41```4243или, что то же самое:4445```text46c:\Temp>c:\Python35\python -m venv myenv47```4849При запуске с флагом `-h` команда отображает доступные параметры:5051```text52usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear]53 [--upgrade] [--without-pip]54 ENV_DIR [ENV_DIR ...]5556Creates virtual Python environments in one or more target directories.5758positional arguments:59 ENV_DIR A directory to create the environment in.6061optional arguments:62 -h, --help show this help message and exit63 --system-site-packages Give the virtual environment access to the system64 site-packages dir.65 --symlinks Try to use symlinks rather than copies, when symlinks66 are not the default for the platform.67 --copies Try to use copies rather than symlinks, even when68 symlinks are the default for the platform.69 --clear Delete the contents of the environment directory if it70 already exists, before environment creation.71 --upgrade Upgrade the environment directory to use this version72 of Python, assuming Python has been upgraded in-place.73 --without-pip Skips installing or upgrading pip in the virtual74 environment (pip is bootstrapped by default)75```7677В зависимости от того, как была вызвана функциональность `venv`, сообщение об использовании может незначительно отличаться, например, ссылаться на `pyvenv` вместо `venv`.7879Изменено в версии 3.4: По умолчанию устанавливается pip, добавлены опции `--without-pip` и `--copies`8081Изменено в версии 3.4: В более ранних версиях, если целевой каталог уже существовал, возникала ошибка, если только не был указан параметр `--clear` или `--upgrade`. Теперь, если указан существующий каталог, его содержимое удаляется и каталог обрабатывается так, как если бы он был только что создан.8283Созданный файл `pyvenv.cfg` также включает ключ `include-system-site-packages`, установленный в `true`, если `venv` запущен с опцией `--system-site-packages`, и в `false` в противном случае.8485Если не указана опция `--without-pip`, будет вызван [`ensurepip`](https://python-all.ru/3.5/library/ensurepip.html#module-ensurepip) для начальной установки `pip` в виртуальное окружение.8687Можно указать несколько путей `pyvenv`, в этом случае на каждом из указанных путей будет создан идентичный виртуальный env в соответствии с заданными параметрами.8889После создания venv его можно «активировать» с помощью скрипта в каталоге с исполняемыми файлами venv. Вызов скрипта зависит от платформы:9091| Платформа | Оболочка | Команда активации виртуального окружения |92| --- | --- | --- |93| Posix | bash/zsh | $ source \<venv\>/bin/activate |94| | fish | $ . \<venv\>/bin/activate.fish |95| | csh/tcsh | $ source \<venv\>/bin/activate.csh |96| Windows | cmd.exe | C:\\\> \<venv\>\\Scripts\\activate.bat |97| | PowerShell | PS C:\\\> \<venv\>\\Scripts\\Activate.ps1 |9899Строго говоря, *нет необходимости* активировать окружение; активация просто добавляет каталог с исполняемыми файлами venv в начало пути, так что «python» вызывает интерпретатор Python из venv, и можно запускать установленные скрипты без указания полного пути. Однако все скрипты, установленные в venv, должны быть работоспособны и без активации, и автоматически использовать Python из venv.100101Можно деактивировать venv, введя «deactivate» в оболочке. Точный механизм зависит от платформы: например, скрипт активации Bash определяет функцию «deactivate», тогда как в Windows есть отдельные скрипты `deactivate.bat` и `Deactivate.ps1`, которые устанавливаются при создании venv.102103Новое в версии 3.4: `fish` и `csh` скрипты активации.104105> **Примечание**106>107> Виртуальное окружение (также называемое `venv`) – это среда Python, в которой интерпретатор Python, библиотеки и скрипты, установленные в ней, изолированы от установленных в других виртуальных окружениях и (по умолчанию) от любых библиотек, установленных в «системном» Python, то есть в том, который установлен как часть операционной системы.108>109> Venv – это дерево каталогов, содержащее исполняемые файлы Python и другие файлы, указывающие на то, что это venv.110>111> Обычные инструменты установки, такие как `Setuptools` и `pip`, работают с venv как ожидается – то есть, когда venv активен, они устанавливают пакеты Python в venv без необходимости явно указывать это.112>113> Когда venv активен (т.е. работает интерпретатор Python из venv), атрибуты [`sys.prefix`](https://python-all.ru/3.5/library/sys.html#sys.prefix) и [`sys.exec_prefix`](https://python-all.ru/3.5/library/sys.html#sys.exec_prefix) указывают на базовый каталог venv, тогда как [`sys.base_prefix`](https://python-all.ru/3.5/library/sys.html#sys.base_prefix) и [`sys.base_exec_prefix`](https://python-all.ru/3.5/library/sys.html#sys.base_exec_prefix) указывают на установку Python вне venv, которая использовалась для создания venv. Если venv не активен, то [`sys.prefix`](https://python-all.ru/3.5/library/sys.html#sys.prefix) совпадает с [`sys.base_prefix`](https://python-all.ru/3.5/library/sys.html#sys.base_prefix) и [`sys.exec_prefix`](https://python-all.ru/3.5/library/sys.html#sys.exec_prefix) совпадает с [`sys.base_exec_prefix`](https://python-all.ru/3.5/library/sys.html#sys.base_exec_prefix) (все они указывают на установку Python вне venv).114>115> Когда venv активен, любые параметры, изменяющие путь установки, будут игнорироваться во всех файлах конфигурации distutils, чтобы предотвратить случайную установку проектов за пределами виртуального окружения.116>117> При работе в командной оболочке пользователи могут активировать venv, запустив скрипт `activate` в каталоге исполняемых файлов venv (точное имя файла зависит от оболочки), который добавляет каталог исполняемых файлов venv в начало переменной окружения `PATH` для текущей оболочки. В других ситуациях активировать venv не требуется – скрипты, установленные в venv, содержат строку shebang, указывающую на интерпретатор Python из venv. Это означает, что скрипт будет запускаться с этим интерпретатором независимо от значения `PATH`. В Windows обработка shebang поддерживается, если установлен Python Launcher for Windows (это было добавлено в Python 3.3 – подробнее см. [**PEP 397**](https://python-all.ru/3.5/library/venv.html)). Таким образом, двойной щелчок по установленному скрипту в окне Проводника Windows запустит скрипт с правильным интерпретатором без необходимости указывать его venv в `PATH`.118119## 28.3.2. API120121Описанный выше высокоуровневый метод использует простой API, предоставляющий механизмы для создателей сторонних виртуальных окружений, чтобы настраивать создание окружения по своему усмотрению – класс [`EnvBuilder`](https://python-all.ru/3.5/library/venv.html#venv.EnvBuilder).122123#### `class venv.EnvBuilder(system_site_packages=False, clear=False, symlinks=False, upgrade=False, with_pip=False)`124125Класс [`EnvBuilder`](https://python-all.ru/3.5/library/venv.html#venv.EnvBuilder) принимает следующие именованные аргументы при создании экземпляра:126127- `system_site_packages` – логическое значение, указывающее, что системные site-packages Python должны быть доступны окружению (по умолчанию `False`).128- `clear` – логическое значение: если истинно, удаляет содержимое любого существующего целевого каталога перед созданием окружения.129- `symlinks` – логическое значение, указывающее, следует ли создавать символическую ссылку на двоичный файл Python (и любые необходимые DLL или другие двоичные файлы, например `pythonw.exe`) вместо копирования. По умолчанию `True` в Linux и Unix-системах, но `False` в Windows.130- `upgrade` – логическое значение: если истинно, обновляет существующее окружение с текущим Python – для использования, когда этот Python был обновлен на месте (по умолчанию `False`).131- `with_pip` – логическое значение: если истинно, гарантирует установку pip в виртуальное окружение. Для этого используется [`ensurepip`](https://python-all.ru/3.5/library/ensurepip.html#module-ensurepip) с опцией `--default-pip`.132133Изменено в версии 3.4: Добавлен параметр `with_pip`134135Создатели сторонних инструментов для виртуальных окружений могут свободно использовать предоставленный класс `EnvBuilder` в качестве базового класса.136137Возвращаемый env-builder – это объект, у которого есть метод `create`:138139#### `create(env_dir)`140141Этот метод принимает в качестве обязательного аргумента путь (абсолютный или относительный к текущему каталогу) целевого каталога, который должен содержать виртуальное окружение. Метод `create` либо создаст окружение в указанном каталоге, либо вызовет соответствующее исключение.142143Метод `create` класса `EnvBuilder` иллюстрирует хуки, доступные для настройки подклассов:144145```python146def create(self, env_dir):147 """148 Создаёт виртуализированное окружение Python в указанном каталоге.149 Параметр env_dir – это целевой каталог, в котором создаётся окружение.150 """151 env_dir = os.path.abspath(env_dir)152 context = self.ensure_directories(env_dir)153 self.create_configuration(context)154 self.setup_python(context)155 self.setup_scripts(context)156 self.post_setup(context)157```158159Каждый из методов [`ensure_directories()`](https://python-all.ru/3.5/library/venv.html#venv.EnvBuilder.ensure_directories), [`create_configuration()`](https://python-all.ru/3.5/library/venv.html#venv.EnvBuilder.create_configuration), [`setup_python()`](https://python-all.ru/3.5/library/venv.html#venv.EnvBuilder.setup_python), [`setup_scripts()`](https://python-all.ru/3.5/library/venv.html#venv.EnvBuilder.setup_scripts) и [`post_setup()`](https://python-all.ru/3.5/library/venv.html#venv.EnvBuilder.post_setup) может быть переопределён.160161#### `ensure_directories(env_dir)`162163Создаёт каталог окружения и все необходимые каталоги, а затем возвращает объект контекста. Это просто контейнер для атрибутов (например, путей), используемый другими методами. Каталоги могут уже существовать, при условии, что были указаны `clear` или `upgrade`, чтобы разрешить работу с существующим каталогом окружения.164165#### `create_configuration(context)`166167Создаёт файл конфигурации `pyvenv.cfg` в окружении.168169#### `setup_python(context)`170171Создает копию исполняемого файла Python (а в Windows – DLL) в окружении. В POSIX-системе, если был использован конкретный исполняемый файл `python3.x`, будут созданы симлинки на `python` и `python3`, указывающие на этот исполняемый файл, если файлы с такими именами уже не существуют.172173#### `setup_scripts(context)`174175Устанавливает скрипты активации, соответствующие платформе, в виртуальное окружение.176177#### `post_setup(context)`178179Метод-заглушка, который может быть переопределён в сторонних реализациях для предварительной установки пакетов в виртуальное окружение или выполнения других действий после создания.180181Кроме того, [`EnvBuilder`](https://python-all.ru/3.5/library/venv.html#venv.EnvBuilder) предоставляет этот вспомогательный метод, который можно вызвать из [`setup_scripts()`](https://python-all.ru/3.5/library/venv.html#venv.EnvBuilder.setup_scripts) или [`post_setup()`](https://python-all.ru/3.5/library/venv.html#venv.EnvBuilder.post_setup) в подклассах для установки пользовательских скриптов в виртуальное окружение.182183#### `install_scripts(context, path)`184185*path* – это путь к каталогу, который должен содержать подкаталоги «common», «posix», «nt», каждый из которых содержит скрипты, предназначенные для каталога bin в окружении. Содержимое «common» и каталога, соответствующего [`os.name`](https://python-all.ru/3.5/library/os.html#os.name), копируется после замены некоторых текстовых плейсхолдеров:186187- `__VENV_DIR__` заменяется на абсолютный путь к каталогу окружения.188- `__VENV_NAME__` заменяется на имя окружения (последний сегмент пути к каталогу окружения).189- `__VENV_PROMPT__` заменяется на приглашение (имя окружения в скобках и с последующим пробелом)190- `__VENV_BIN_NAME__` заменяется на имя каталога bin ( `bin` или `Scripts`).191- `__VENV_PYTHON__` заменяется на абсолютный путь к исполняемому файлу окружения.192193Каталоги могут существовать (на случай, когда обновляется существующее окружение).194195Также существует удобная функция уровня модуля:196197#### `venv.create(env_dir, system_site_packages=False, clear=False, symlinks=False, with_pip=False)`198199Создаёт экземпляр [`EnvBuilder`](https://python-all.ru/3.5/library/venv.html#venv.EnvBuilder) с заданными именованными аргументами и вызывает его метод [`create()`](https://python-all.ru/3.5/library/venv.html#venv.EnvBuilder.create) с аргументом *env\_dir*.200201Изменено в версии 3.4: Добавлен параметр `with_pip`202203## 28.3.3. Пример расширения `EnvBuilder`204205Следующий скрипт показывает, как расширить [`EnvBuilder`](https://python-all.ru/3.5/library/venv.html#venv.EnvBuilder), реализуя подкласс, который устанавливает setuptools и pip в созданную виртуальную среду:206207```python208import os209import os.path210from subprocess import Popen, PIPE211import sys212from threading import Thread213from urllib.parse import urlparse214from urllib.request import urlretrieve215import venv216217class ExtendedEnvBuilder(venv.EnvBuilder):218 """219 Данный построитель устанавливает setuptools и pip, чтобы с их помощью можно было220 Установка других пакетов в созданное окружение с помощью easy_install.221222 :param nodist: Если True, setuptools и pip не устанавливаются в223 созданное окружение.224 :param nopip: Если True, pip не устанавливается в создаваемое225 окружение.226 :param progress: Если setuptools или pip устанавливаются, за ходом установки227 можно следить, передав вызываемый объект для отслеживания прогресса.228 Если он указан, то вызывается с двумя229 аргументами: строкой, описывающей текущий этап, и230 контекстом, указывающим, откуда пришла эта строка.231 Аргумент context может принимать одно из трёх значений:232 'main' – вызов происходит из самой virtualize(),233 а также 'stdout' и 'stderr' – строки берутся234 из потоков вывода подпроцесса, который235 используется для установки приложения.236237 Если вызываемый объект не указан, по умолчанию сведения о ходе выполнения238 выводятся в sys.stderr.239 """240241 def __init__(self, *args, **kwargs):242 self.nodist = kwargs.pop('nodist', False)243 self.nopip = kwargs.pop('nopip', False)244 self.progress = kwargs.pop('progress', None)245 self.verbose = kwargs.pop('verbose', False)246 super().__init__(*args, **kwargs)247248 def post_setup(self, context):249 """250 Устанавливает пакеты, которые необходимо предварительно установить в создаваемое виртуальное окружение.251 создаваемое окружение.252253 :param context: Информация для запроса на создание окружения254 обрабатываемого.255 """256 os.environ['VIRTUAL_ENV'] = context.env_dir257 if not self.nodist:258 self.install_setuptools(context)259 # Читает строки из потока вывода подпроцесса и либо передаёт их вызываемому объекту для отслеживания хода выполнения260 if not self.nopip and not self.nodist:261 self.install_pip(context)262263 def reader(self, stream, context):264 """265 Читает строки из потока вывода подпроцесса и передаёт их в индикатор прогресса266 Загружает скрипт в папку с бинарными файлами виртуального окружения267 """268 progress = self.progress269 while True:270 s = stream.readline()271 if not s:272 break273 if progress is not None:274 progress(s, context)275 else:276 if not self.verbose:277 sys.stderr.write('.')278 else:279 sys.stderr.write(s.decode('utf-8'))280 sys.stderr.flush()281 stream.close()282283 def install_script(self, context, name, url):284 _, _, path, _, _, _ = urlparse(url)285 fn = os.path.split(path)[-1]286 binpath = context.bin_path287 distpath = os.path.join(binpath, fn)288 # Скачать скрипт в папку bin окружения289 urlretrieve(url, distpath)290 progress = self.progress291 if self.verbose:292 term = '\n'293 else:294 term = ''295 if progress is not None:296 progress('Installing %s ...%s' % (name, term), 'main')297 else:298 sys.stderr.write('Installing %s ...%s' % (name, term))299 sys.stderr.flush()300 # Установить в окружение301 args = [context.env_exe, fn]302 p = Popen(args, stdout=PIPE, stderr=PIPE, cwd=binpath)303 t1 = Thread(target=self.reader, args=(p.stdout, 'stdout'))304 t1.start()305 t2 = Thread(target=self.reader, args=(p.stderr, 'stderr'))306 t2.start()307 p.wait()308 t1.join()309 t2.join()310 if progress is not None:311 progress('done.', 'main')312 else:313 sys.stderr.write('done.\n')314 # Очищает – больше не требуется315 os.unlink(distpath)316317 def install_setuptools(self, context):318 """319 Установить setuptools в окружение.320321 :param context: Информация для запроса на создание окружения322 обрабатываемого.323 """324 url = 'https://bitbucket.org/pypa/setuptools/downloads/ez_setup.py'325 self.install_script(context, 'setuptools', url)326 # Устанавливает pip в виртуальное окружение.327 pred = lambda o: o.startswith('setuptools-') and o.endswith('.tar.gz')328 files = filter(pred, os.listdir(context.bin_path))329 for f in files:330 f = os.path.join(context.bin_path, f)331 os.unlink(f)332333 def install_pip(self, context):334 """335 Установить pip в окружение.336337 :param context: Информация для запроса на создание окружения338 обрабатываемого.339 """340 url = 'https://raw.github.com/pypa/pip/master/contrib/get-pip.py'341 self.install_script(context, 'pip', url)342343def main(args=None):344 compatible = True345 if sys.version_info < (3, 3):346 compatible = False347 elif not hasattr(sys, 'base_prefix'):348 compatible = False349 if not compatible:350 raise ValueError('This script is only for use with '351 'Python 3.3 or later')352 else:353 import argparse354355 parser = argparse.ArgumentParser(prog=__name__,356 description='Creates virtual Python '357 'environments in one or '358 'more target '359 'directories.')360 parser.add_argument('dirs', metavar='ENV_DIR', nargs='+',361 help='A directory to create the environment in.')362 parser.add_argument('--no-setuptools', default=False,363 action='store_true', dest='nodist',364 help="Don't install setuptools or pip in the "365 "virtual environment.")366 parser.add_argument('--no-pip', default=False,367 action='store_true', dest='nopip',368 help="Don't install pip in the virtual "369 "environment.")370 parser.add_argument('--system-site-packages', default=False,371 action='store_true', dest='system_site',372 help='Give the virtual environment access to the '373 'system site-packages dir.')374 if os.name == 'nt':375 use_symlinks = False376 else:377 use_symlinks = True378 parser.add_argument('--symlinks', default=use_symlinks,379 action='store_true', dest='symlinks',380 help='Try to use symlinks rather than copies, '381 'when symlinks are not the default for '382 'the platform.')383 parser.add_argument('--clear', default=False, action='store_true',384 dest='clear', help='Delete the contents of the '385 'environment directory if it '386 'already exists, before '387 'environment creation.')388 parser.add_argument('--upgrade', default=False, action='store_true',389 dest='upgrade', help='Upgrade the environment '390 'directory to use this version '391 'of Python, assuming Python '392 'has been upgraded in-place.')393 parser.add_argument('--verbose', default=False, action='store_true',394 dest='verbose', help='Display the output '395 'from the scripts which '396 'install setuptools and pip.')397 options = parser.parse_args(args)398 if options.upgrade and options.clear:399 raise ValueError('you cannot supply --upgrade and --clear together.')400 builder = ExtendedEnvBuilder(system_site_packages=options.system_site,401 clear=options.clear,402 symlinks=options.symlinks,403 upgrade=options.upgrade,404 nodist=options.nodist,405 nopip=options.nopip,406 verbose=options.verbose)407 for d in options.dirs:408 builder.create(d)409410if __name__ == '__main__':411 rc = 1412 try:413 main()414 rc = 0415 except Exception as e:416 print('Error: %s' % e, file=sys.stderr)417 sys.exit(rc)418```419420Этот скрипт также доступен для загрузки [онлайн](https://python-all.ru/3.5/library/venv.html).421