> **Источник:** https://python-all.ru/3.9/library/venv.html > > «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor. --- # [`venv`](https://python-all.ru/3.9/library/venv.html#module-venv) – Создание виртуальных окружений Новое в версии 3.3. **Исходный код:** [Lib/venv/](https://python-all.ru/src/3.9/Lib/venv) --- Модуль [`venv`](https://python-all.ru/3.9/library/venv.html#module-venv) предоставляет поддержку создания легковесных «виртуальных окружений» со своими собственными каталогами сайт-пакетов, опционально изолированными от системных каталогов сайт-пакетов. Каждое виртуальное окружение имеет свой собственный двоичный файл Python (который соответствует версии двоичного файла, использованного для создания этого окружения) и может иметь свой независимый набор установленных пакетов Python в своих каталогах сайт-пакетов. За дополнительной информацией о виртуальных окружениях Python обращайтесь к [**PEP 405**](https://python-all.ru/3.9/library/venv.html). > **См. также** > > [Руководство пользователя по упаковке Python: создание и использование виртуальных окружений](https://python-all.ru/3.9/library/venv.html) ## Создание виртуальных окружений Создание [виртуальных окружений](https://python-all.ru/3.9/library/venv.html#venv-def) выполняется с помощью команды `venv`: ```python python3 -m venv /path/to/new/virtual/environment ``` Выполнение этой команды создает целевой каталог (создавая все родительские каталоги, которые еще не существуют) и помещает в него файл `pyvenv.cfg` с ключом `home`, указывающим на установку Python, из которой была запущена команда (обычное имя для целевого каталога – `.venv`). Она также создает подкаталог `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.9/dev/whatsnew/3.6.html#deprecated-features). Изменено в версии 3.5: Теперь для создания виртуальных окружений рекомендуется использовать `venv`. В Windows команда `venv` выполняется следующим образом: ```text c:\>c:\Python35\python -m venv c:\path\to\myenv ``` Альтернативно, если вы настроили переменные `PATH` и `PATHEXT` для вашей [установки Python](https://python-all.ru/3.9/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] [--prompt PROMPT] [--upgrade-deps] 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) --prompt PROMPT Provides an alternative prompt prefix for this environment. --upgrade-deps Upgrade core dependencies: pip setuptools to the latest version in PyPI Once an environment has been created, you may wish to activate it, e.g. by sourcing an activate script in its bin directory. ``` Изменено в версии 3.9: Добавлена опция `--upgrade-deps` для обновления pip и setuptools до последних версий на PyPI Изменено в версии 3.4: По умолчанию устанавливается pip, добавлены опции `--without-pip` и `--copies` Изменено в версии 3.4: В более ранних версиях, если целевой каталог уже существовал, возникала ошибка, если не была предоставлена опция `--clear` или `--upgrade`. > **Примечание** > > Хотя символические ссылки поддерживаются в Windows, они не рекомендуются. Особенно важно отметить, что двойной щелчок по `python.exe` в Проводнике разрешит символьную ссылку немедленно и проигнорирует виртуальное окружение. > **Примечание** > > В Microsoft Windows может потребоваться включить сценарий `Activate.ps1`, установив политику выполнения для пользователя. Это можно сделать, выполнив следующую команду PowerShell: > > PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser > > См. [О политиках выполнения](https://python-all.ru/3.9/library/venv.html) для получения дополнительной информации. Созданный файл `pyvenv.cfg` также включает ключ `include-system-site-packages`, установленный в `true`, если `venv` запущен с опцией `--system-site-packages`, и в `false` в противном случае. Если не указана опция `--without-pip`, будет вызван [`ensurepip`](https://python-all.ru/3.9/library/ensurepip.html#module-ensurepip) для начальной установки `pip` в виртуальное окружение. Можно указать несколько путей для `venv`, в этом случае будет создано идентичное виртуальное окружение с заданными опциями для каждого указанного пути. После создания виртуального окружения его можно «активировать» с помощью скрипта в каталоге исполняемых файлов виртуального окружения. Вызов скрипта зависит от платформы (*\* необходимо заменить на путь к каталогу, содержащему виртуальное окружение): | Платформа | Оболочка | Команда активации виртуального окружения | | --- | --- | --- | | POSIX | bash/zsh | $ source \/bin/activate | | | fish | $ source \/bin/activate.fish | | | csh/tcsh | $ source \/bin/activate.csh | | | PowerShell Core | $ \/bin/Activate.ps1 | | Windows | cmd.exe | C:\\\> \\\Scripts\\activate.bat | | | PowerShell | PS C:\\\> \\\Scripts\\Activate.ps1 | Когда виртуальное окружение активно, переменная окружения `VIRTUAL_ENV` устанавливается в путь к виртуальному окружению. Это можно использовать для проверки, работает ли программа внутри виртуального окружения. Активировать окружение *не обязательно*; активация просто добавляет каталог исполняемых файлов виртуального окружения в начало вашего PATH, так что «python» запускает интерпретатор Python из виртуального окружения, и вы можете запускать установленные скрипты без указания полного пути. Однако все скрипты, установленные в виртуальном окружении, должны быть запускаемы без его активации и будут автоматически использовать Python из виртуального окружения. Деактивировать виртуальное окружение можно, введя «deactivate» в оболочке. Точный механизм зависит от платформы и является внутренней деталью реализации (обычно используется скрипт или функция оболочки). Новое в версии 3.4: `fish` и `csh` скрипты активации. Новое в версии 3.8: Скрипты активации PowerShell устанавливаются в POSIX для поддержки PowerShell Core. > **Примечание** > > Виртуальное окружение – это среда Python, в которой интерпретатор Python, библиотеки и скрипты, установленные в неё, изолированы от установленных в других виртуальных окружениях, а также (по умолчанию) от любых библиотек, установленных в «системном» Python, то есть в Python, установленном как часть вашей операционной системы. > > Виртуальное окружение – это дерево каталогов, содержащее исполняемые файлы Python и другие файлы, указывающие на то, что это виртуальное окружение. > > Распространённые инструменты установки, такие как [setuptools](https://python-all.ru/3.9/library/venv.html) и [pip](https://python-all.ru/3.9/library/venv.html), корректно работают с виртуальными окружениями. Другими словами, когда виртуальное окружение активно, они устанавливают пакеты Python в виртуальное окружение без необходимости явного указания. > > Когда виртуальное окружение активно (т.е. запущен интерпретатор Python из виртуального окружения), атрибуты [`sys.prefix`](https://python-all.ru/3.9/library/sys.html#sys.prefix) и [`sys.exec_prefix`](https://python-all.ru/3.9/library/sys.html#sys.exec_prefix) указывают на базовый каталог виртуального окружения, тогда как [`sys.base_prefix`](https://python-all.ru/3.9/library/sys.html#sys.base_prefix) и [`sys.base_exec_prefix`](https://python-all.ru/3.9/library/sys.html#sys.base_exec_prefix) указывают на установку Python вне виртуального окружения, которая использовалась для создания виртуального окружения. Если виртуальное окружение не активно, то [`sys.prefix`](https://python-all.ru/3.9/library/sys.html#sys.prefix) совпадает с [`sys.base_prefix`](https://python-all.ru/3.9/library/sys.html#sys.base_prefix), а [`sys.exec_prefix`](https://python-all.ru/3.9/library/sys.html#sys.exec_prefix) совпадает с [`sys.base_exec_prefix`](https://python-all.ru/3.9/library/sys.html#sys.base_exec_prefix) (все они указывают на установку Python вне виртуального окружения). > > Когда виртуальное окружение активно, любые параметры, изменяющие путь установки, будут игнорироваться во всех файлах конфигурации [`distutils`](https://python-all.ru/3.9/library/distutils.html#module-distutils), чтобы предотвратить непреднамеренную установку проектов за пределами виртуального окружения. > > При работе в командной оболочке пользователи могут активировать виртуальное окружение, запустив скрипт `activate` в каталоге исполняемых файлов виртуального окружения (точное имя файла и команда для его использования зависят от оболочки), который добавляет каталог исполняемых файлов виртуального окружения в начало переменной окружения `PATH` для текущей оболочки. В других случаях активировать виртуальное окружение не требуется; скрипты, установленные в виртуальные окружения, содержат строку shebang, указывающую на интерпретатор Python из виртуального окружения. Это означает, что скрипт будет выполняться этим интерпретатором независимо от значения `PATH`. В Windows обработка строки shebang поддерживается, если установлен Python Launcher для Windows (это было добавлено в Python 3.3 – см. [**PEP 397**](https://python-all.ru/3.9/library/venv.html) для подробностей). Таким образом, двойной щелчок по установленному скрипту в окне Проводника Windows должен запускать скрипт с правильным интерпретатором без необходимости ссылаться на его виртуальное окружение в `PATH`. ## API Описанный выше высокоуровневый метод использует простой API, предоставляющий механизмы для создателей сторонних виртуальных окружений, чтобы настраивать создание окружения по своему усмотрению – класс [`EnvBuilder`](https://python-all.ru/3.9/library/venv.html#venv.EnvBuilder). #### `class venv.EnvBuilder(system_site_packages=False, clear=False, symlinks=False, upgrade=False, with_pip=False, prompt=None, upgrade_deps=False)` Класс [`EnvBuilder`](https://python-all.ru/3.9/library/venv.html#venv.EnvBuilder) принимает следующие именованные аргументы при создании экземпляра: - `system_site_packages` – логическое значение, указывающее, что системные site-packages Python должны быть доступны окружению (по умолчанию `False`). - `clear` – логическое значение: если истинно, удаляет содержимое любого существующего целевого каталога перед созданием окружения. - `symlinks` – логическое значение, указывающее, следует ли пытаться создать символическую ссылку на бинарный файл Python вместо копирования. - `upgrade` – логическое значение: если истинно, обновляет существующее окружение с текущим Python – для использования, когда этот Python был обновлен на месте (по умолчанию `False`). - `with_pip` – логическое значение: если истинно, гарантирует установку pip в виртуальное окружение. Для этого используется [`ensurepip`](https://python-all.ru/3.9/library/ensurepip.html#module-ensurepip) с опцией `--default-pip`. - `prompt` – строка, используемая после активации виртуального окружения (по умолчанию `None`, что означает, что будет использовано имя каталога окружения). Если указана специальная строка `"."`, в качестве приглашения используется имя текущего каталога. - `upgrade_deps` – Обновляет базовые модули venv до последних на PyPI Изменено в версии 3.4: Добавлен параметр `with_pip` Новое в версии 3.6: Добавлен параметр `prompt` Новое в версии 3.9: Добавлен параметр `upgrade_deps` Создатели сторонних инструментов для виртуальных окружений могут свободно использовать предоставленный класс [`EnvBuilder`](https://python-all.ru/3.9/library/venv.html#venv.EnvBuilder) в качестве базового класса. Возвращаемый env-builder – это объект, у которого есть метод `create`: #### `create(env_dir)` Создаёт виртуальное окружение путём указания целевого каталога (абсолютного или относительного по отношению к текущему каталогу), который будет содержать виртуальное окружение. Метод `create` либо создаст окружение в указанном каталоге, либо вызовет соответствующее исключение. Метод `create` класса [`EnvBuilder`](https://python-all.ru/3.9/library/venv.html#venv.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.9/library/venv.html#venv.EnvBuilder.ensure_directories), [`create_configuration()`](https://python-all.ru/3.9/library/venv.html#venv.EnvBuilder.create_configuration), [`setup_python()`](https://python-all.ru/3.9/library/venv.html#venv.EnvBuilder.setup_python), [`setup_scripts()`](https://python-all.ru/3.9/library/venv.html#venv.EnvBuilder.setup_scripts) и [`post_setup()`](https://python-all.ru/3.9/library/venv.html#venv.EnvBuilder.post_setup) может быть переопределён. #### `ensure_directories(env_dir)` Создаёт каталог окружения и все необходимые каталоги, а затем возвращает объект контекста. Это просто контейнер для атрибутов (например, путей), используемый другими методами. Каталоги могут уже существовать, при условии, что были указаны `clear` или `upgrade`, чтобы разрешить работу с существующим каталогом окружения. #### `create_configuration(context)` Создаёт файл конфигурации `pyvenv.cfg` в окружении. #### `setup_python(context)` Создаёт копию или символическую ссылку на исполняемый файл Python в окружении. В системах POSIX, если был указан конкретный исполняемый файл `python3.x`, будут созданы символические ссылки на `python` и `python3`, указывающие на этот исполняемый файл, если файлы с такими именами уже не существуют. #### `setup_scripts(context)` Устанавливает скрипты активации, соответствующие платформе, в виртуальное окружение. #### `upgrade_dependencies(context)` Обновляет основные пакеты зависимостей venv (в настоящее время `pip` и `setuptools`) в окружении. Для этого вызывается исполняемый файл `pip` внутри окружения. Новое в версии 3.9. #### `post_setup(context)` Метод-заглушка, который может быть переопределён в сторонних реализациях для предварительной установки пакетов в виртуальное окружение или выполнения других действий после создания. Изменено в версии 3.7.2: В Windows теперь используются скрипты-перенаправители для `python[w].exe` вместо копирования самих исполняемых файлов. В версии 3.7.2 только [`setup_python()`](https://python-all.ru/3.9/library/venv.html#venv.EnvBuilder.setup_python) ничего не делает, если не запущен из сборки в исходном дереве. Изменено в версии 3.7.3: В Windows скрипты-перенаправители копируются как часть [`setup_python()`](https://python-all.ru/3.9/library/venv.html#venv.EnvBuilder.setup_python) вместо [`setup_scripts()`](https://python-all.ru/3.9/library/venv.html#venv.EnvBuilder.setup_scripts). В версии 3.7.2 это было не так. При использовании символьных ссылок будут связаны исходные исполняемые файлы. Кроме того, [`EnvBuilder`](https://python-all.ru/3.9/library/venv.html#venv.EnvBuilder) предоставляет этот вспомогательный метод, который можно вызвать из [`setup_scripts()`](https://python-all.ru/3.9/library/venv.html#venv.EnvBuilder.setup_scripts) или [`post_setup()`](https://python-all.ru/3.9/library/venv.html#venv.EnvBuilder.post_setup) в подклассах для установки пользовательских скриптов в виртуальное окружение. #### `install_scripts(context, path)` *path* – это путь к каталогу, который должен содержать подкаталоги «common», «posix», «nt», каждый из которых содержит скрипты, предназначенные для каталога bin в окружении. Содержимое «common» и каталога, соответствующего [`os.name`](https://python-all.ru/3.9/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, prompt=None)` Создаёт экземпляр [`EnvBuilder`](https://python-all.ru/3.9/library/venv.html#venv.EnvBuilder) с заданными именованными аргументами и вызывает его метод [`create()`](https://python-all.ru/3.9/library/venv.html#venv.EnvBuilder.create) с аргументом *env\_dir*. Новое в версии 3.3. Изменено в версии 3.4: Добавлен параметр `with_pip` Изменено в версии 3.6: Добавлен параметр `prompt` ## Пример расширения `EnvBuilder` Следующий скрипт показывает, как расширить [`EnvBuilder`](https://python-all.ru/3.9/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: Если истина, setuptools и pip не устанавливаются в созданное виртуальное окружение. :param nopip: Если истина, 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://bootstrap.pypa.io/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.9/library/venv.html).