venv.md
1> **Источник:** https://python-all.ru/3.4/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.4/library/venv.html#module-venv) – Создание виртуальных окружений89Новое в версии 3.3.1011**Исходный код:** [Lib/venv](https://python-all.ru/src/3.4/Lib/venv)1213---1415Модуль [`venv`](https://python-all.ru/3.4/library/venv.html#module-venv) предоставляет поддержку для создания легковесных «виртуальных окружений» с собственными каталогами site, которые могут быть изолированы от системных каталогов site. Каждое виртуальное окружение имеет собственный двоичный файл Python (что позволяет создавать окружения с разными версиями Python) и может иметь собственный независимый набор установленных пакетов Python в своих каталогах site.1617За дополнительной информацией о виртуальных окружениях Python обращайтесь к [**PEP 405**](https://python-all.ru/3.4/library/venv.html).1819## 28.3.1. Создание виртуальных окружений2021Создание [*виртуальных окружений*](https://python-all.ru/3.4/library/venv.html#venv-def) производится выполнением скрипта `pyvenv`:2223```python24pyvenv /path/to/new/virtual/environment25```2627Выполнение этой команды создает целевой каталог (создавая все родительские каталоги, которых еще нет) и помещает в него файл `pyvenv.cfg` с ключом `home`, указывающим на установку Python, из которой была запущена команда. Она также создает подкаталог `bin` (или `Scripts` в Windows), содержащий копию двоичного файла `python` (или нескольких файлов в случае Windows). Также создается (изначально пустой) подкаталог `lib/pythonX.Y/site-packages` (в Windows это `Lib\site-packages`).2829> **См. также**30>31> [Руководство пользователя по упаковке Python: создание и использование виртуальных окружений](https://python-all.ru/3.4/library/venv.html)3233В Windows может потребоваться запускать скрипт `pyvenv` следующим образом, если не заданы соответствующие переменные PATH и PATHEXT:3435```text36c:\Temp>c:\Python34\python c:\Python34\Tools\Scripts\pyvenv.py myenv37```3839или, что то же самое:4041```text42c:\Temp>c:\Python34\python -m venv myenv43```4445Команда, запущенная с `-h`, покажет доступные параметры:4647```text48usage: venv [-h] [--system-site-packages] [--symlinks] [--clear]49 [--upgrade] [--without-pip] ENV_DIR [ENV_DIR ...]5051Creates virtual Python environments in one or more target directories.5253positional arguments:54 ENV_DIR A directory to create the environment in.5556optional arguments:57 -h, --help show this help message and exit58 --system-site-packages Give access to the global site-packages dir to the59 virtual environment.60 --symlinks Try to use symlinks rather than copies, when symlinks61 are not the default for the platform.62 --copies Try to use copies rather than symlinks, even when63 symlinks are the default for the platform.64 --clear Delete the environment directory if it already exists.65 If not specified and the directory exists, an error is66 raised.67 --upgrade Upgrade the environment directory to use this version68 of Python, assuming Python has been upgraded in-place.69 --without-pip Skips installing or upgrading pip in the virtual70 environment (pip is bootstrapped by default)71```7273В зависимости от того, как была вызвана функциональность `venv`, сообщение об использовании может незначительно отличаться, например, ссылаться на `pyvenv` вместо `venv`.7475Изменено в версии 3.4: Устанавливает pip по умолчанию, добавлены параметры `--without-pip` и `--copies`7677Изменено в версии 3.4: В более ранних версиях, если целевой каталог уже существовал, возникала ошибка, если только не был указан параметр `--clear` или `--upgrade`. Теперь, если указан существующий каталог, его содержимое удаляется, и каталог обрабатывается так, как если бы он был только что создан.7879Созданный файл `pyvenv.cfg` также содержит ключ `include-system-site-packages`, установленный в `true`, если `venv` был запущен с параметром `--system-site-packages`, и в `false` в противном случае.8081Если не указан параметр `--without-pip`, будет вызван модуль [`ensurepip`](https://python-all.ru/3.4/library/ensurepip.html#module-ensurepip) для установки `pip` в виртуальное окружение.8283Можно указать несколько путей для `pyvenv`; в этом случае идентичное виртуальное окружение будет создано в соответствии с заданными параметрами по каждому указанному пути.8485После создания venv его можно «активировать» с помощью скрипта в каталоге с исполняемыми файлами venv. Вызов скрипта зависит от платформы:8687| Платформа | Оболочка | Команда активации виртуального окружения |88| --- | --- | --- |89| Posix | bash/zsh | $ source \<venv\>/bin/activate |90| | fish | $ . \<venv\>/bin/activate.fish |91| | csh/tcsh | $ source \<venv\>/bin/activate.csh |92| Windows | cmd.exe | C:\> \<venv\>/Scripts/activate.bat |93| | PowerShell | PS C:\> \<venv\>/Scripts/Activate.ps1 |9495Строго говоря, *нет необходимости* активировать окружение; активация просто добавляет каталог с исполняемыми файлами venv в начало пути, так что «python» вызывает интерпретатор Python из venv, и можно запускать установленные скрипты без указания полного пути. Однако все скрипты, установленные в venv, должны быть работоспособны и без активации, и автоматически использовать Python из venv.9697Деактивировать venv можно, набрав «deactivate» в оболочке. Точный механизм зависит от платформы: например, скрипт активации Bash определяет функцию «deactivate», тогда как в Windows есть отдельные скрипты `deactivate.bat` и `Deactivate.ps1`, которые устанавливаются при создании venv.9899Новое в версии 3.4: Скрипты активации для `fish` и `csh`.100101> **Примечание**102>103> Виртуальное окружение (также называемое `venv`) – это среда Python, в которой интерпретатор, библиотеки и скрипты, установленные в нее, изолированы от установленных в других виртуальных окружениях, а также (по умолчанию) от любых библиотек, установленных в «системном» Python, т.е. том, который установлен как часть вашей операционной системы.104>105> Venv – это дерево каталогов, содержащее исполняемые файлы Python и другие файлы, указывающие на то, что это venv.106>107> Обычные инструменты установки, такие как `Setuptools` и `pip`, работают с venvs как ожидается – т.е. когда venv активен, они устанавливают пакеты Python в venv без необходимости явного указания. Конечно, сначала нужно установить их в venv: это можно сделать, запустив `ez_setup.py` при активном venv, а затем запустив `easy_install pip`. В качестве альтернативы можно загрузить исходные архивы и после распаковки запустить `python setup.py install` при активном venv.108>109> Когда venv активен (т.е. работает интерпретатор Python из этого venv), атрибуты [`sys.prefix`](https://python-all.ru/3.4/library/sys.html#sys.prefix) и [`sys.exec_prefix`](https://python-all.ru/3.4/library/sys.html#sys.exec_prefix) указывают на базовый каталог venv, тогда как [`sys.base_prefix`](https://python-all.ru/3.4/library/sys.html#sys.base_prefix) и [`sys.base_exec_prefix`](https://python-all.ru/3.4/library/sys.html#sys.base_exec_prefix) указывают на установку Python вне venv, которая использовалась для создания venv. Если venv не активен, то [`sys.prefix`](https://python-all.ru/3.4/library/sys.html#sys.prefix) совпадает с [`sys.base_prefix`](https://python-all.ru/3.4/library/sys.html#sys.base_prefix), а [`sys.exec_prefix`](https://python-all.ru/3.4/library/sys.html#sys.exec_prefix) совпадает с [`sys.base_exec_prefix`](https://python-all.ru/3.4/library/sys.html#sys.base_exec_prefix) (все они указывают на установку Python вне venv).110>111> Когда venv активен, любые параметры, изменяющие путь установки, будут игнорироваться во всех файлах конфигурации distutils, чтобы предотвратить случайную установку проектов за пределами виртуального окружения.112>113> При работе в командной оболочке пользователи могут активировать 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.4/library/venv.html) для подробностей). Таким образом, двойной щелчок по установленному скрипту в окне Проводника Windows должен запускать скрипт с правильным интерпретатором, без необходимости указывать на его venv в `PATH`.114115## 28.3.2. API116117Описанный выше высокоуровневый метод использует простой API, предоставляющий механизмы для создателей сторонних виртуальных окружений, чтобы настраивать создание окружений в соответствии с их потребностями, – класс [`EnvBuilder`](https://python-all.ru/3.4/library/venv.html#venv.EnvBuilder).118119#### `class venv.EnvBuilder(system_site_packages=False, clear=False, symlinks=False, upgrade=False, with_pip=False)`120121Класс [`EnvBuilder`](https://python-all.ru/3.4/library/venv.html#venv.EnvBuilder) принимает следующие именованные аргументы при создании экземпляра:122123- `system_site_packages` – логическое значение, указывающее, что системные пакеты site-packages Python должны быть доступны в окружении (по умолчанию `False`).124- `clear` – логическое значение, которое при значении true удаляет содержимое любой существующей целевой директории перед созданием окружения.125- `symlinks` – логическое значение, указывающее, следует ли пытаться создавать символические ссылки на исполняемый файл Python (и любые необходимые DLL или другие двоичные файлы, например `pythonw.exe`) вместо копирования. По умолчанию `True` в Linux и Unix-системах, и `False` в Windows.126- `upgrade` – логическое значение, которое при значении true обновляет существующее окружение с помощью запущенного Python – для случаев, когда этот Python был обновлён на месте (по умолчанию `False`).127- `with_pip` – логическое значение, которое при значении true гарантирует установку pip в виртуальном окружении. Для этого используется [`ensurepip`](https://python-all.ru/3.4/library/ensurepip.html#module-ensurepip) с опцией `--default-pip`.128129Изменено в версии 3.4: Добавлен параметр `with_pip`130131Создатели сторонних инструментов для виртуальных окружений смогут использовать предоставленный класс `EnvBuilder` в качестве базового.132133Возвращаемый построитель окружения (env-builder) – это объект, имеющий метод `create`:134135#### `create(env_dir)`136137Этот метод принимает в качестве обязательного аргумента путь (абсолютный или относительный к текущей директории) к целевой директории, в которой должно быть создано виртуальное окружение. Метод `create` либо создаст окружение в указанной директории, либо возбудит соответствующее исключение.138139Метод `create` класса `EnvBuilder` иллюстрирует точки расширения (hooks), доступные для настройки в подклассах:140141```python142def create(self, env_dir):143 """144 Создаёт виртуализированное окружение Python в указанном каталоге.145 Параметр env_dir – это целевой каталог, в котором создаётся окружение.146 """147 env_dir = os.path.abspath(env_dir)148 context = self.ensure_directories(env_dir)149 self.create_configuration(context)150 self.setup_python(context)151 self.setup_scripts(context)152 self.post_setup(context)153```154155Каждый из методов [`ensure_directories()`](https://python-all.ru/3.4/library/venv.html#venv.EnvBuilder.ensure_directories), [`create_configuration()`](https://python-all.ru/3.4/library/venv.html#venv.EnvBuilder.create_configuration), [`setup_python()`](https://python-all.ru/3.4/library/venv.html#venv.EnvBuilder.setup_python), [`setup_scripts()`](https://python-all.ru/3.4/library/venv.html#venv.EnvBuilder.setup_scripts) и [`post_setup()`](https://python-all.ru/3.4/library/venv.html#venv.EnvBuilder.post_setup) может быть переопределён.156157#### `ensure_directories(env_dir)`158159Создаёт директорию окружения и все необходимые каталоги, и возвращает объект контекста. Это просто контейнер для атрибутов (таких как пути), используемый другими методами. Директории могут уже существовать, если были указаны `clear` или `upgrade`, чтобы разрешить работу с существующей директорией окружения.160161#### `create_configuration(context)`162163Создаёт конфигурационный файл `pyvenv.cfg` в окружении.164165#### `setup_python(context)`166167Создаёт копию исполняемого файла Python (и, в Windows, DLL) в окружении. В POSIX-системе, если использовался конкретный исполняемый файл `python3.x`, будут созданы символические ссылки на `python` и `python3`, указывающие на этот исполняемый файл, если файлы с такими именами уже не существуют.168169#### `setup_scripts(context)`170171Устанавливает скрипты активации, соответствующие платформе, в виртуальное окружение.172173#### `post_setup(context)`174175Метод-заглушка, который может быть переопределён в сторонних реализациях для предварительной установки пакетов в виртуальное окружение или выполнения других действий после создания.176177Кроме того, [`EnvBuilder`](https://python-all.ru/3.4/library/venv.html#venv.EnvBuilder) предоставляет вспомогательный метод, который можно вызывать из [`setup_scripts()`](https://python-all.ru/3.4/library/venv.html#venv.EnvBuilder.setup_scripts) или [`post_setup()`](https://python-all.ru/3.4/library/venv.html#venv.EnvBuilder.post_setup) в подклассах для помощи в установке пользовательских скриптов в виртуальное окружение.178179#### `install_scripts(context, path)`180181*path* – это путь к директории, которая должна содержать подкаталоги «common», «posix», «nt», каждый из которых содержит скрипты, предназначенные для каталога bin в окружении. Содержимое «common» и каталога, соответствующего [`os.name`](https://python-all.ru/3.4/library/os.html#os.name), копируется после замены некоторых плейсхолдеров в тексте:182183- `__VENV_DIR__` заменяется на абсолютный путь к директории окружения.184- `__VENV_NAME__` заменяется на имя окружения (последний сегмент пути директории окружения).185- `__VENV_PROMPT__` заменяется на приглашение (имя окружения в круглых скобках с пробелом после).186- `__VENV_BIN_NAME__` заменяется на имя каталога bin (либо `bin`, либо `Scripts`).187- `__VENV_PYTHON__` заменяется на абсолютный путь к исполняемому файлу окружения.188189Каталоги могут существовать (на случай, когда обновляется существующее окружение).190191Также существует удобная функция уровня модуля:192193#### `venv.create(env_dir, system_site_packages=False, clear=False, symlinks=False, with_pip=False)`194195Создаёт [`EnvBuilder`](https://python-all.ru/3.4/library/venv.html#venv.EnvBuilder) с заданными именованными аргументами и вызывает его [`create()`](https://python-all.ru/3.4/library/venv.html#venv.EnvBuilder.create) метод с аргументом *env\_dir*.196197Изменено в версии 3.4: Добавлен параметр `with_pip`198199## 28.3.3. Пример расширения `EnvBuilder`200201Следующий скрипт показывает, как расширить [`EnvBuilder`](https://python-all.ru/3.4/library/venv.html#venv.EnvBuilder), реализовав подкласс, который устанавливает setuptools и pip в созданную виртуальную среду venv:202203```python204import os205import os.path206from subprocess import Popen, PIPE207import sys208from threading import Thread209from urllib.parse import urlparse210from urllib.request import urlretrieve211import venv212213class ExtendedEnvBuilder(venv.EnvBuilder):214 """215 Данный построитель устанавливает setuptools и pip, чтобы с их помощью можно было216 Установка других пакетов в созданное окружение с помощью easy_install.217218 :param nodist: Если True, setuptools и pip не устанавливаются в219 созданное окружение.220 :param nopip: Если True, pip не устанавливается в создаваемое221 окружение.222 :param progress: Если setuptools или pip устанавливаются, за ходом установки223 можно следить, передав вызываемый объект для отслеживания прогресса.224 Если он указан, то вызывается с двумя225 аргументами: строкой, описывающей текущий этап, и226 контекстом, указывающим, откуда пришла эта строка.227 Аргумент context может принимать одно из трёх значений:228 'main' – вызов происходит из самой virtualize(),229 а также 'stdout' и 'stderr' – строки берутся230 из потоков вывода подпроцесса, который231 используется для установки приложения.232233 Если вызываемый объект не указан, по умолчанию сведения о ходе выполнения234 выводятся в sys.stderr.235 """236237 def __init__(self, *args, **kwargs):238 self.nodist = kwargs.pop('nodist', False)239 self.nopip = kwargs.pop('nopip', False)240 self.progress = kwargs.pop('progress', None)241 self.verbose = kwargs.pop('verbose', False)242 super().__init__(*args, **kwargs)243244 def post_setup(self, context):245 """246 Устанавливает пакеты, которые необходимо предварительно установить в создаваемое виртуальное окружение.247 создаваемое окружение.248249 :param context: Информация для запроса на создание окружения250 обрабатываемого.251 """252 os.environ['VIRTUAL_ENV'] = context.env_dir253 if not self.nodist:254 self.install_setuptools(context)255 # Читает строки из потока вывода подпроцесса и либо передаёт их вызываемому объекту для отслеживания хода выполнения256 if not self.nopip and not self.nodist:257 self.install_pip(context)258259 def reader(self, stream, context):260 """261 Читает строки из потока вывода подпроцесса и передаёт их в индикатор прогресса262 Загружает скрипт в папку с бинарными файлами виртуального окружения263 """264 progress = self.progress265 while True:266 s = stream.readline()267 if not s:268 break269 if progress is not None:270 progress(s, context)271 else:272 if not self.verbose:273 sys.stderr.write('.')274 else:275 sys.stderr.write(s.decode('utf-8'))276 sys.stderr.flush()277 stream.close()278279 def install_script(self, context, name, url):280 _, _, path, _, _, _ = urlparse(url)281 fn = os.path.split(path)[-1]282 binpath = context.bin_path283 distpath = os.path.join(binpath, fn)284 # Скачать скрипт в папку bin окружения285 urlretrieve(url, distpath)286 progress = self.progress287 if self.verbose:288 term = '\n'289 else:290 term = ''291 if progress is not None:292 progress('Installing %s ...%s' % (name, term), 'main')293 else:294 sys.stderr.write('Installing %s ...%s' % (name, term))295 sys.stderr.flush()296 # Установить в окружение297 args = [context.env_exe, fn]298 p = Popen(args, stdout=PIPE, stderr=PIPE, cwd=binpath)299 t1 = Thread(target=self.reader, args=(p.stdout, 'stdout'))300 t1.start()301 t2 = Thread(target=self.reader, args=(p.stderr, 'stderr'))302 t2.start()303 p.wait()304 t1.join()305 t2.join()306 if progress is not None:307 progress('done.', 'main')308 else:309 sys.stderr.write('done.\n')310 # Очищает – больше не требуется311 os.unlink(distpath)312313 def install_setuptools(self, context):314 """315 Установить setuptools в окружение.316317 :param context: Информация для запроса на создание окружения318 обрабатываемого.319 """320 url = 'https://bitbucket.org/pypa/setuptools/downloads/ez_setup.py'321 self.install_script(context, 'setuptools', url)322 # Устанавливает pip в виртуальное окружение.323 pred = lambda o: o.startswith('setuptools-') and o.endswith('.tar.gz')324 files = filter(pred, os.listdir(context.bin_path))325 for f in files:326 f = os.path.join(context.bin_path, f)327 os.unlink(f)328329 def install_pip(self, context):330 """331 Установить pip в окружение.332333 :param context: Информация для запроса на создание окружения334 обрабатываемого.335 """336 url = 'https://raw.github.com/pypa/pip/master/contrib/get-pip.py'337 self.install_script(context, 'pip', url)338339def main(args=None):340 compatible = True341 if sys.version_info < (3, 3):342 compatible = False343 elif not hasattr(sys, 'base_prefix'):344 compatible = False345 if not compatible:346 raise ValueError('This script is only for use with '347 'Python 3.3 or later')348 else:349 import argparse350351 parser = argparse.ArgumentParser(prog=__name__,352 description='Creates virtual Python '353 'environments in one or '354 'more target '355 'directories.')356 parser.add_argument('dirs', metavar='ENV_DIR', nargs='+',357 help='A directory to create the environment in.')358 parser.add_argument('--no-setuptools', default=False,359 action='store_true', dest='nodist',360 help="Don't install setuptools or pip in the "361 "virtual environment.")362 parser.add_argument('--no-pip', default=False,363 action='store_true', dest='nopip',364 help="Don't install pip in the virtual "365 "environment.")366 parser.add_argument('--system-site-packages', default=False,367 action='store_true', dest='system_site',368 help='Give the virtual environment access to the '369 'system site-packages dir.')370 if os.name == 'nt':371 use_symlinks = False372 else:373 use_symlinks = True374 parser.add_argument('--symlinks', default=use_symlinks,375 action='store_true', dest='symlinks',376 help='Try to use symlinks rather than copies, '377 'when symlinks are not the default for '378 'the platform.')379 parser.add_argument('--clear', default=False, action='store_true',380 dest='clear', help='Delete the contents of the '381 'environment directory if it '382 'already exists, before '383 'environment creation.')384 parser.add_argument('--upgrade', default=False, action='store_true',385 dest='upgrade', help='Upgrade the environment '386 'directory to use this version '387 'of Python, assuming Python '388 'has been upgraded in-place.')389 parser.add_argument('--verbose', default=False, action='store_true',390 dest='verbose', help='Display the output '391 'from the scripts which '392 'install setuptools and pip.')393 options = parser.parse_args(args)394 if options.upgrade and options.clear:395 raise ValueError('you cannot supply --upgrade and --clear together.')396 builder = ExtendedEnvBuilder(system_site_packages=options.system_site,397 clear=options.clear,398 symlinks=options.symlinks,399 upgrade=options.upgrade,400 nodist=options.nodist,401 nopip=options.nopip,402 verbose=options.verbose)403 for d in options.dirs:404 builder.create(d)405406if __name__ == '__main__':407 rc = 1408 try:409 main()410 rc = 0411 except Exception as e:412 print('Error: %s' % e, file=sys.stderr)413 sys.exit(rc)414```415416Этот скрипт также доступен для загрузки [онлайн](https://python-all.ru/3.4/library/venv.html).417