> **Источник:** https://python-all.ru/3.6/library/venv.html > > «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor. --- # 28.3. [`venv`](https://python-all.ru/3.6/library/venv.html#module-venv) – Создание виртуальных окружений Новое в версии 3.3. **Исходный код:** [Lib/venv/](https://python-all.ru/src/3.6/Lib/venv) --- Модуль [`venv`](https://python-all.ru/3.6/library/venv.html#module-venv) предоставляет поддержку для создания легковесных «виртуальных окружений» с собственными site-каталогами, опционально изолированными от системных site-каталогов. Каждое виртуальное окружение имеет собственный бинарный файл Python (что позволяет создавать окружения с разными версиями Python) и может иметь свой независимый набор установленных пакетов Python в своих site-каталогах. За дополнительной информацией о виртуальных окружениях Python обращайтесь к [**PEP 405**](https://python-all.ru/3.6/library/venv.html). > **Примечание** > > Скрипт `pyvenv` устарел начиная с Python 3.6 в пользу использования `python3 -m venv`, чтобы предотвратить возможную путаницу относительно того, на каком интерпретаторе Python будет основано виртуальное окружение. ## 28.3.1. Создание виртуальных окружений Создание [виртуальных окружений](https://python-all.ru/3.6/library/venv.html#venv-def) выполняется с помощью команды `venv`: ```python python3 -m venv /path/to/new/virtual/environment ``` Выполнение этой команды создаёт целевой каталог (создавая все родительские каталоги, которые ещё не существуют) и помещает в него файл `pyvenv.cfg` с ключом `home`, указывающим на установку Python, из которой была запущена команда. Также создаётся подкаталог `bin` (или `Scripts` в Windows), содержащий копию или символическую ссылку на исполняемый файл Python (в зависимости от платформы или аргументов, указанных при создании окружения). Кроме того, создаётся (изначально пустой) подкаталог `lib/pythonX.Y/site-packages` (в Windows это `Lib\site-packages`). Если указан существующий каталог, он будет использован повторно. Устарело с версии 3.6: `pyvenv` был рекомендованным инструментом для создания виртуальных окружений в Python 3.3 и 3.4, и [объявлен устаревшим в Python 3.6](https://python-all.ru/3.6/dev/whatsnew/3.6.html#deprecated-features). Изменено в версии 3.5: Теперь для создания виртуальных окружений рекомендуется использовать `venv`. > **См. также** > > [Руководство пользователя по упаковке Python: создание и использование виртуальных окружений](https://python-all.ru/3.6/library/venv.html) В Windows команда `venv` выполняется следующим образом: ```text c:\>c:\Python35\python -m venv c:\path\to\myenv ``` Альтернативно, если вы настроили переменные `PATH` и `PATHEXT` для вашей [установки Python](https://python-all.ru/3.6/using/windows.html#using-on-windows): ```text c:\>python -m venv c:\path\to\myenv ``` При запуске с флагом `-h` команда отображает доступные параметры: ```text usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear] [--upgrade] [--without-pip] ENV_DIR [ENV_DIR ...] Creates virtual Python environments in one or more target directories. positional arguments: ENV_DIR A directory to create the environment in. optional arguments: -h, --help show this help message and exit --system-site-packages Give the virtual environment access to the system site-packages dir. --symlinks Try to use symlinks rather than copies, when symlinks are not the default for the platform. --copies Try to use copies rather than symlinks, even when symlinks are the default for the platform. --clear Delete the contents of the environment directory if it already exists, before environment creation. --upgrade Upgrade the environment directory to use this version of Python, assuming Python has been upgraded in-place. --without-pip Skips installing or upgrading pip in the virtual environment (pip is bootstrapped by default) Once an environment has been created, you may wish to activate it, e.g. by sourcing an activate script in its bin directory. ``` Изменено в версии 3.4: По умолчанию устанавливается pip, добавлены опции `--without-pip` и `--copies` Изменено в версии 3.4: В более ранних версиях, если целевой каталог уже существовал, возникала ошибка, если не была предоставлена опция `--clear` или `--upgrade`. Созданный файл `pyvenv.cfg` также включает ключ `include-system-site-packages`, установленный в `true`, если `venv` запущен с опцией `--system-site-packages`, и в `false` в противном случае. Если не указана опция `--without-pip`, будет вызван [`ensurepip`](https://python-all.ru/3.6/library/ensurepip.html#module-ensurepip) для начальной установки `pip` в виртуальное окружение. Можно указать несколько путей для `venv`, в этом случае будет создано идентичное виртуальное окружение с заданными опциями для каждого указанного пути. После создания виртуального окружения его можно «активировать» с помощью скрипта в каталоге исполняемых файлов виртуального окружения. Вызов скрипта зависит от платформы (*\* необходимо заменить на путь к каталогу, содержащему виртуальное окружение): | Платформа | Оболочка | Команда активации виртуального окружения | | --- | --- | --- | | Posix | bash/zsh | $ source \/bin/activate | | | fish | $ . \/bin/activate.fish | | | csh/tcsh | $ source \/bin/activate.csh | | Windows | cmd.exe | C:\\\> \\\Scripts\\activate.bat | | | PowerShell | PS C:\\\> \\\Scripts\\Activate.ps1 | Активировать окружение *не обязательно*; активация просто добавляет каталог исполняемых файлов виртуального окружения в начало вашего PATH, так что «python» запускает интерпретатор Python из виртуального окружения, и вы можете запускать установленные скрипты без указания полного пути. Однако все скрипты, установленные в виртуальном окружении, должны быть запускаемы без его активации и будут автоматически использовать Python из виртуального окружения. Деактивировать виртуальное окружение можно, введя «deactivate» в оболочке. Точный механизм зависит от платформы: например, скрипт активации Bash определяет функцию «deactivate», тогда как в Windows существуют отдельные скрипты `deactivate.bat` и `Deactivate.ps1`, которые устанавливаются при создании виртуального окружения. Новое в версии 3.4: `fish` и `csh` скрипты активации. > **Примечание** > > Виртуальное окружение – это среда Python, в которой интерпретатор Python, библиотеки и скрипты, установленные в неё, изолированы от установленных в других виртуальных окружениях, а также (по умолчанию) от любых библиотек, установленных в «системном» Python, то есть в Python, установленном как часть вашей операционной системы. > > Виртуальное окружение – это дерево каталогов, содержащее исполняемые файлы Python и другие файлы, указывающие на то, что это виртуальное окружение. > > Обычные инструменты установки, такие как `Setuptools` и `pip`, работают с виртуальными окружениями как ожидается. Другими словами, когда виртуальное окружение активно, они устанавливают пакеты Python в виртуальное окружение без необходимости явного указания. > > Когда виртуальное окружение активно (т.е. запущен интерпретатор 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 вне виртуального окружения). > > Когда виртуальное окружение активно, любые параметры, изменяющие путь установки, будут игнорироваться во всех файлах конфигурации distutils, чтобы предотвратить случайную установку проектов за пределами виртуального окружения. > > При работе в командной оболочке пользователи могут активировать виртуальное окружение, запустив скрипт `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`. ## 28.3.2. API Описанный выше высокоуровневый метод использует простой API, предоставляющий механизмы для создателей сторонних виртуальных окружений, чтобы настраивать создание окружения по своему усмотрению – класс [`EnvBuilder`](https://python-all.ru/3.6/library/venv.html#venv.EnvBuilder). #### `class venv.EnvBuilder(system_site_packages=False, clear=False, symlinks=False, upgrade=False, with_pip=False, prompt=None)` Класс [`EnvBuilder`](https://python-all.ru/3.6/library/venv.html#venv.EnvBuilder) принимает следующие именованные аргументы при создании экземпляра: - `system_site_packages` – логическое значение, указывающее, что системные site-packages Python должны быть доступны окружению (по умолчанию `False`). - `clear` – логическое значение: если истинно, удаляет содержимое любого существующего целевого каталога перед созданием окружения. - `symlinks` – логическое значение, указывающее, следует ли пытаться создать симлинк на бинарный файл Python (и любые необходимые DLL или другие бинарные файлы, например `pythonw.exe`) вместо копирования. - `upgrade` – логическое значение: если истинно, обновляет существующее окружение с текущим Python – для использования, когда этот Python был обновлен на месте (по умолчанию `False`). - `with_pip` – логическое значение: если истинно, гарантирует установку pip в виртуальное окружение. Для этого используется [`ensurepip`](https://python-all.ru/3.6/library/ensurepip.html#module-ensurepip) с опцией `--default-pip`. - `prompt` – строка, используемая после активации виртуального окружения (по умолчанию равна `None`, то есть будет использовано имя каталога окружения). Изменено в версии 3.4: Добавлен параметр `with_pip` Новое в версии 3.6: Добавлен параметр `prompt` Создатели сторонних инструментов для виртуальных окружений могут свободно использовать предоставленный класс `EnvBuilder` в качестве базового класса. Возвращаемый env-builder – это объект, у которого есть метод `create`: #### `create(env_dir)` Этот метод принимает в качестве обязательного аргумента путь (абсолютный или относительный к текущему каталогу) целевого каталога, который должен содержать виртуальное окружение. Метод `create` либо создаст окружение в указанном каталоге, либо вызовет соответствующее исключение. Метод `create` класса `EnvBuilder` иллюстрирует хуки, доступные для настройки подклассов: ```python def create(self, env_dir): """ Создаёт виртуализированное окружение Python в указанном каталоге. Параметр env_dir – это целевой каталог, в котором создаётся окружение. """ env_dir = os.path.abspath(env_dir) context = self.ensure_directories(env_dir) self.create_configuration(context) self.setup_python(context) self.setup_scripts(context) self.post_setup(context) ``` Каждый из методов [`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) может быть переопределён. #### `ensure_directories(env_dir)` Создаёт каталог окружения и все необходимые каталоги, а затем возвращает объект контекста. Это просто контейнер для атрибутов (например, путей), используемый другими методами. Каталоги могут уже существовать, при условии, что были указаны `clear` или `upgrade`, чтобы разрешить работу с существующим каталогом окружения. #### `create_configuration(context)` Создаёт файл конфигурации `pyvenv.cfg` в окружении. #### `setup_python(context)` Создает копию исполняемого файла Python (а в Windows – DLL) в окружении. В POSIX-системе, если был использован конкретный исполняемый файл `python3.x`, будут созданы симлинки на `python` и `python3`, указывающие на этот исполняемый файл, если файлы с такими именами уже не существуют. #### `setup_scripts(context)` Устанавливает скрипты активации, соответствующие платформе, в виртуальное окружение. #### `post_setup(context)` Метод-заглушка, который может быть переопределён в сторонних реализациях для предварительной установки пакетов в виртуальное окружение или выполнения других действий после создания. Кроме того, [`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) в подклассах для установки пользовательских скриптов в виртуальное окружение. #### `install_scripts(context, path)` *path* – это путь к каталогу, который должен содержать подкаталоги «common», «posix», «nt», каждый из которых содержит скрипты, предназначенные для каталога bin в окружении. Содержимое «common» и каталога, соответствующего [`os.name`](https://python-all.ru/3.6/library/os.html#os.name), копируется после замены некоторых текстовых плейсхолдеров: - `__VENV_DIR__` заменяется на абсолютный путь к каталогу окружения. - `__VENV_NAME__` заменяется на имя окружения (последний сегмент пути к каталогу окружения). - `__VENV_PROMPT__` заменяется на приглашение (имя окружения в скобках и с последующим пробелом) - `__VENV_BIN_NAME__` заменяется на имя каталога bin ( `bin` или `Scripts`). - `__VENV_PYTHON__` заменяется на абсолютный путь к исполняемому файлу окружения. Каталоги могут существовать (на случай, когда обновляется существующее окружение). Также существует удобная функция уровня модуля: #### `venv.create(env_dir, system_site_packages=False, clear=False, symlinks=False, with_pip=False)` Создаёт экземпляр [`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*. Изменено в версии 3.4: Добавлен параметр `with_pip` ## 28.3.3. Пример расширения `EnvBuilder` Следующий скрипт показывает, как расширить [`EnvBuilder`](https://python-all.ru/3.6/library/venv.html#venv.EnvBuilder), реализовав подкласс, который устанавливает setuptools и pip в созданное виртуальное окружение: ```python import os import os.path from subprocess import Popen, PIPE import sys from threading import Thread from urllib.parse import urlparse from urllib.request import urlretrieve import venv class ExtendedEnvBuilder(venv.EnvBuilder): """ Данный построитель устанавливает setuptools и pip, чтобы с их помощью можно было устанавливать другие пакеты в созданное виртуальное окружение командой pip или easy_install. :param nodist: Если True, setuptools и pip не устанавливаются в созданное виртуальное окружение. :param nopip: Если True, pip не устанавливается в создаваемое виртуальное окружение. :param progress: Если setuptools или pip устанавливаются, за ходом установки можно следить, передав вызываемый объект для отслеживания прогресса. Если он указан, то вызывается с двумя аргументами: строкой, описывающей текущий этап, и контекстом, указывающим, откуда пришла эта строка. Аргумент context может принимать одно из трёх значений: 'main' – вызов происходит из самой virtualize(), а также 'stdout' и 'stderr' – строки берутся из потоков вывода подпроцесса, который используется для установки приложения. Если вызываемый объект не указан, по умолчанию сведения о ходе выполнения выводятся в sys.stderr. """ def __init__(self, *args, **kwargs): self.nodist = kwargs.pop('nodist', False) self.nopip = kwargs.pop('nopip', False) self.progress = kwargs.pop('progress', None) self.verbose = kwargs.pop('verbose', False) super().__init__(*args, **kwargs) def post_setup(self, context): """ Устанавливает пакеты, которые необходимо предварительно установить в создаваемое виртуальное окружение. создаваемое виртуальное окружение обрабатываемого запроса на создание виртуального окружения запрос на создание обрабатывается """ os.environ['VIRTUAL_ENV'] = context.env_dir if not self.nodist: self.install_setuptools(context) # Читает строки из потока вывода подпроцесса и либо передаёт их вызываемому объекту для отслеживания хода выполнения if not self.nopip and not self.nodist: self.install_pip(context) def reader(self, stream, context): """ Читает строки из потока вывода подпроцесса и передаёт их в индикатор прогресса Загружает скрипт в папку с бинарными файлами виртуального окружения """ progress = self.progress while True: s = stream.readline() if not s: break if progress is not None: progress(s, context) else: if not self.verbose: sys.stderr.write('.') else: sys.stderr.write(s.decode('utf-8')) sys.stderr.flush() stream.close() def install_script(self, context, name, url): _, _, path, _, _, _ = urlparse(url) fn = os.path.split(path)[-1] binpath = context.bin_path distpath = os.path.join(binpath, fn) # Устанавливает в виртуальное окружение urlretrieve(url, distpath) progress = self.progress if self.verbose: term = '\n' else: term = '' if progress is not None: progress('Installing %s ...%s' % (name, term), 'main') else: sys.stderr.write('Installing %s ...%s' % (name, term)) sys.stderr.flush() # Очистка – больше не требуется args = [context.env_exe, fn] p = Popen(args, stdout=PIPE, stderr=PIPE, cwd=binpath) t1 = Thread(target=self.reader, args=(p.stdout, 'stdout')) t1.start() t2 = Thread(target=self.reader, args=(p.stderr, 'stderr')) t2.start() p.wait() t1.join() t2.join() if progress is not None: progress('done.', 'main') else: sys.stderr.write('done.\n') # Очищает – больше не требуется os.unlink(distpath) def install_setuptools(self, context): """ Устанавливает setuptools в виртуальное окружение обрабатываемого запроса на создание виртуального окружения запрос на создание обрабатывается """ url = 'https://bitbucket.org/pypa/setuptools/downloads/ez_setup.py' self.install_script(context, 'setuptools', url) # Устанавливает pip в виртуальное окружение. pred = lambda o: o.startswith('setuptools-') and o.endswith('.tar.gz') files = filter(pred, os.listdir(context.bin_path)) for f in files: f = os.path.join(context.bin_path, f) os.unlink(f) def install_pip(self, context): """ Устанавливает pip в виртуальное окружение обрабатываемого запроса на создание виртуального окружения запрос на создание обрабатывается """ url = 'https://raw.github.com/pypa/pip/master/contrib/get-pip.py' self.install_script(context, 'pip', url) def main(args=None): compatible = True if sys.version_info < (3, 3): compatible = False elif not hasattr(sys, 'base_prefix'): compatible = False if not compatible: raise ValueError('This script is only for use with ' 'Python 3.3 or later') else: import argparse parser = argparse.ArgumentParser(prog=__name__, description='Creates virtual Python ' 'environments in one or ' 'more target ' 'directories.') parser.add_argument('dirs', metavar='ENV_DIR', nargs='+', help='A directory in which to create the 'virtual environment.') parser.add_argument('--no-setuptools', default=False, action='store_true', dest='nodist', help="Don't install setuptools or pip in the " "virtual environment.") parser.add_argument('--no-pip', default=False, action='store_true', dest='nopip', help="Don't install pip in the virtual " "environment.") parser.add_argument('--system-site-packages', default=False, action='store_true', dest='system_site', help='Give the virtual environment access to the ' 'system site-packages dir.') if os.name == 'nt': use_symlinks = False else: use_symlinks = True parser.add_argument('--symlinks', default=use_symlinks, action='store_true', dest='symlinks', help='Try to use symlinks rather than copies, ' 'when symlinks are not the default for ' 'the platform.') parser.add_argument('--clear', default=False, action='store_true', dest='clear', help='Delete the contents of the ' 'virtual environment ' 'directory if it already ' 'exists, before virtual ' 'environment creation.') parser.add_argument('--upgrade', default=False, action='store_true', dest='upgrade', help='Upgrade the virtual ' 'environment directory to ' 'use this version of ' 'Python, assuming Python ' 'has been upgraded ' 'in-place.') parser.add_argument('--verbose', default=False, action='store_true', dest='verbose', help='Display the output ' 'from the scripts which ' 'install setuptools and pip.') options = parser.parse_args(args) if options.upgrade and options.clear: raise ValueError('you cannot supply --upgrade and --clear together.') builder = ExtendedEnvBuilder(system_site_packages=options.system_site, clear=options.clear, symlinks=options.symlinks, upgrade=options.upgrade, nodist=options.nodist, nopip=options.nopip, verbose=options.verbose) for d in options.dirs: builder.create(d) if __name__ == '__main__': rc = 1 try: main() rc = 0 except Exception as e: print('Error: %s' % e, file=sys.stderr) sys.exit(rc) ``` Этот скрипт также доступен для загрузки [онлайн](https://python-all.ru/3.6/library/venv.html).