venv
— Создание виртуальных сред¶
Added in version 3.3.
Источник: Lib/venv/
Модуль venv
поддерживает создание легких «виртуальных сред», каждая из которых имеет свой собственный независимый набор пакетов Python, установленных в их site
каталогах. Виртуальная среда создается поверх существующей установки Python, известной как «базовый» Python виртуальной среды, и может быть по желанию изолирована от пакетов базовой среды, так что доступны только те, которые явно установлены в виртуальной среде.
При использовании из виртуальной среды обычные инструменты установки, такие как pip, будут устанавливать пакеты Python в виртуальную среду без необходимости явного указания.
Виртуальная среда - это (помимо прочего):
Используется для размещения определенного интерпретатора Python и программных библиотек и двоичных файлов, необходимых для поддержки проекта (библиотеки или приложения). По умолчанию они изолированы от программного обеспечения в других виртуальных средах, а также от интерпретаторов и библиотек Python, установленных в операционной системе.
Содержится в каталоге, условно названном
venv
или.venv
в каталоге проекта, или в каталоге-контейнере для множества виртуальных окружений, например~/.virtualenvs
.Не проверяется в системах контроля исходных текстов, таких как Git.
Считается одноразовым - его должно быть легко удалить и создать заново. Вы не размещаете в окружении код проекта.
Не считается перемещаемым или копируемым - вы просто воссоздаете ту же среду в целевом месте.
Дополнительные сведения о виртуальных средах Python см. в разделе PEP 405.
Availability: не WASI, не iOS.
Этот модуль не работает или недоступен на платформах WebAssembly или iOS. Дополнительные сведения о доступности WASM см. в разделе Платформы WebAssembly; о доступности iOS - в разделе iOS.
Создание виртуальных сред¶
Создание virtual environments осуществляется выполнением команды venv
:
python -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.5: Теперь для создания виртуальных сред рекомендуется использовать значение venv
.
Не рекомендуется, начиная с версии 3.6: pyvenv
был рекомендованным инструментом для создания виртуальных сред для Python 3.3 и 3.4, а стал deprecated in Python 3.6.
В Windows вызовите команду venv
следующим образом:
c:\>Python35\python -m venv c:\path\to\myenv
В качестве альтернативы, если вы настроили переменные PATH
и PATHEXT
для вашего Python installation:
c:\>python -m venv c:\path\to\myenv
Если выполнить команду с -h
, будут показаны доступные опции:
usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear]
[--upgrade] [--without-pip] [--prompt PROMPT] [--upgrade-deps]
[--without-scm-ignore-file]
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.
options:
-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) to the latest
version in PyPI
--without-scm-ignore-file
Skips adding the default SCM ignore file to the
environment directory (the default is a .gitignore
file).
Once an environment has been created, you may wish to activate it, e.g. by
sourcing an activate script in its bin directory.
Изменено в версии 3.13: --without-scm-ignore-file
был добавлен вместе с созданием игнор-файла для git
по умолчанию.
Изменено в версии 3.12: setuptools
больше не является зависимостью от ядра venv.
Изменено в версии 3.9: Добавьте опцию --upgrade-deps
для обновления pip + setuptools до последней версии на PyPI
Изменено в версии 3.4: Устанавливает pip по умолчанию, добавлены опции --without-pip
и --copies
.
Изменено в версии 3.4: В предыдущих версиях, если целевой каталог уже существовал, возникала ошибка, если не была указана опция --clear
или --upgrade
.
Примечание
Хотя симлинки поддерживаются в Windows, использовать их не рекомендуется. Особо следует отметить, что двойной щелчок на python.exe
в File Explorer приведет к тому, что симлинк будет разрешен с нетерпением и проигнорирует виртуальную среду.
Примечание
В Microsoft Windows может потребоваться включить сценарий Activate.ps1
, установив политику выполнения для пользователя. Это можно сделать, выполнив следующую команду PowerShell:
PS C:> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Дополнительные сведения см. в разделе About Execution Policies.
Созданный файл pyvenv.cfg
также включает ключ include-system-site-packages
, установленный на true
, если venv
запущен с опцией --system-site-packages
, и false
в противном случае.
Если не указан параметр --without-pip
, будет вызван ensurepip
для загрузки pip
в виртуальную среду.
В venv
можно указать несколько путей, в этом случае по каждому указанному пути будет создано идентичное виртуальное окружение в соответствии с заданными параметрами.
Как работают венеры¶
Если интерпретатор Python запущен из виртуальной среды, sys.prefix
и sys.exec_prefix
указывают на каталоги виртуальной среды, а sys.base_prefix
и sys.base_exec_prefix
- на каталоги базового Python, использованного для создания среды. Достаточно проверить sys.prefix != sys.base_prefix
, чтобы определить, запущен ли текущий интерпретатор из виртуального окружения.
Виртуальную среду можно «активировать» с помощью скрипта в ее бинарном каталоге (bin
на POSIX; Scripts
на Windows). Это добавит каталог к вашему PATH
, так что запуск python вызовет интерпретатор Python среды, и вы сможете запускать установленные скрипты без необходимости использовать их полный путь. Вызов скрипта активации зависит от платформы (<venv>
должен быть заменен на путь к каталогу, содержащему виртуальную среду):
Платформа |
Ракушка |
Команда для активации виртуальной среды |
---|---|---|
POSIX |
bash/zsh |
|
рыба |
|
|
csh/tcsh |
|
|
PowerShell |
|
|
Windows |
cmd.exe |
|
PowerShell |
|
Added in version 3.4: Скрипты активации fish и csh.
Added in version 3.8: Сценарии активации PowerShell, установленные под POSIX для поддержки PowerShell Core.
Вам не нужно активировать виртуальное окружение, так как вы можете просто указать полный путь к интерпретатору Python этого окружения при вызове Python. Более того, все скрипты, установленные в среде, должны запускаться без ее активации.
Для этого в скриптах, устанавливаемых в виртуальные среды, есть строка «shebang», которая указывает на интерпретатор Python среды, то есть #!/<path-to-venv>/bin/python
. Это означает, что скрипт будет запущен с этим интерпретатором независимо от значения PATH
. В Windows обработка строк «shebang» поддерживается, если у вас установлен Python Launcher для Windows. Таким образом, двойной щелчок на установленном скрипте в окне проводника Windows запустит его с нужным интерпретатором без необходимости активации среды или включения PATH
.
Если виртуальная среда активирована, переменная окружения VIRTUAL_ENV
устанавливается в путь к ней. Поскольку для использования виртуального окружения не требуется его явная активация, на переменную VIRTUAL_ENV
нельзя полагаться, чтобы определить, используется ли виртуальное окружение.
Предупреждение
Поскольку скрипты, установленные в окружениях, не должны ожидать активации окружения, их строки shebang содержат абсолютные пути к интерпретаторам окружения. Из-за этого окружения в общем случае являются непортируемыми. У вас всегда должно быть простое средство воссоздания окружения (например, если у вас есть файл требований requirements.txt
, вы можете вызвать pip install -r requirements.txt
, используя pip
окружения, чтобы установить все пакеты, необходимые окружению). Если по какой-то причине вам нужно переместить окружение в новое место, вам следует создать его в нужном месте и удалить старое. Если вы перемещаете среду, потому что вы переместили ее родительский каталог, вам следует воссоздать среду в ее новом месте. В противном случае программное обеспечение, установленное в среду, может работать не так, как ожидалось.
Вы можете отключить виртуальное окружение, набрав deactivate
в оболочке. Точный механизм зависит от платформы и является деталью внутренней реализации (обычно используется скрипт или функция оболочки).
API¶
Описанный выше высокоуровневый метод использует простой API, который предоставляет сторонним создателям виртуальных сред механизмы для настройки создания среды в соответствии с их потребностями, - класс EnvBuilder
.
- class venv.EnvBuilder(system_site_packages=False, clear=False, symlinks=False, upgrade=False, with_pip=False, prompt=None, upgrade_deps=False, *, scm_ignore_files=frozenset())¶
Класс
EnvBuilder
принимает следующие ключевые аргументы при инстанцировании:system_site_packages
– булево значение, указывающее, что системные Python site-пакеты должны быть доступны окружению (по умолчаниюFalse
).clear
– булево значение, которое, если оно истинно, удалит содержимое любого существующего целевого каталога перед созданием окружения.symlinks
– булево значение, указывающее, пытаться ли симлинковать двоичный файл Python, а не копировать его.upgrade
– булево значение, которое, если оно истинно, обновляет существующее окружение с запущенным Python - для использования, когда этот Python был обновлен на месте (по умолчаниюFalse
).with_pip
– булево значение, которое, если оно истинно, гарантирует, что pip установлен в виртуальной среде. Здесь используетсяensurepip
с опцией--default-pip
.prompt
– строка, которая будет использоваться после активации виртуального окружения (по умолчаниюNone
, что означает, что будет использоваться имя каталога окружения). Если указана специальная строка"."
, то в качестве подсказки будет использоваться базовое имя текущего каталога.upgrade_deps
– Обновление базовых модулей venv до последних версий на PyPIscm_ignore_files
– Создание игнор-файлов для указанных менеджеров управления исходным кодом (SCM) в итерируемой таблице. Поддержка определяется наличием метода с именемcreate_{scm}_ignore_file
. По умолчанию поддерживаются только значения"git"
иcreate_git_ignore_file()
.
Изменено в версии 3.4: Добавлен параметр
with_pip
Изменено в версии 3.6: Добавлен параметр
prompt
Изменено в версии 3.9: Добавлен параметр
upgrade_deps
Изменено в версии 3.13: Добавлен параметр
scm_ignore_files
Создатели сторонних инструментов виртуального окружения смогут свободно использовать предоставленный класс
EnvBuilder
в качестве базового.Возвращаемый env-builder - это объект, который имеет метод
create
:- create(env_dir)¶
Создайте виртуальное окружение, указав целевой каталог (абсолютный или относительный к текущему каталогу), который должен содержать виртуальное окружение. Метод
create
либо создаст среду в указанном каталоге, либо вызовет соответствующее исключение.Метод
create
классаEnvBuilder
иллюстрирует крючки, доступные для настройки подклассов:def create(self, env_dir): """ Create a virtualized Python environment in a directory. env_dir is the target directory to create an environment in. """ 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()
,create_configuration()
,setup_python()
,setup_scripts()
иpost_setup()
может быть переопределен.
- ensure_directories(env_dir)¶
Создает каталог окружения и все необходимые подкаталоги, которые еще не существуют, и возвращает объект контекста. Этот объект контекста является просто держателем атрибутов (таких как пути) для использования другими методами. Если
EnvBuilder
создается с аргументомclear=True
, содержимое каталога окружения будет очищено, а затем все необходимые подкаталоги будут созданы заново.Возвращаемый объект контекста - это
types.SimpleNamespace
со следующими атрибутами:env_dir
- Расположение виртуальной среды. Используется для__VENV_DIR__
в скриптах активации (см.install_scripts()
).env_name
- Имя виртуальной среды. Используется для__VENV_NAME__
в скриптах активации (см.install_scripts()
).prompt
- Подсказка, которая будет использоваться скриптами активации. Используется для__VENV_PROMPT__
в скриптах активации (см.install_scripts()
).executable
- Основной исполняемый файл Python, используемый виртуальной средой. Это учитывает случай, когда виртуальная среда создается из другой виртуальной среды.inc_path
- Путь включения для виртуальной среды.lib_path
- Путь к purelib для виртуальной среды.bin_path
- Путь к сценарию для виртуальной среды.bin_name
- Имя пути сценария относительно расположения виртуальной среды. Используется для__VENV_BIN_NAME__
в скриптах активации (см.install_scripts()
).env_exe
- Имя интерпретатора Python в виртуальной среде. Используется для__VENV_PYTHON__
в скриптах активации (см.install_scripts()
).env_exec_cmd
- Имя интерпретатора Python с учетом перенаправления файловой системы. Его можно использовать для запуска Python в виртуальной среде.
Изменено в версии 3.11: Параметр venv sysconfig installation scheme используется для построения путей к создаваемым каталогам.
Изменено в версии 3.12: Атрибут
lib_path
был добавлен к контексту, и объект контекста был задокументирован.
- create_configuration(context)¶
Создает файл конфигурации
pyvenv.cfg
в среде.
- setup_python(context)¶
Создает копию или симссылку на исполняемый файл Python в окружении. В POSIX-системах, если использовался конкретный исполняемый файл
python3.x
, будут созданы симлинки наpython
иpython3
, указывающие на этот исполняемый файл, если только файлы с такими именами уже не существуют.
- setup_scripts(context)¶
Устанавливает в виртуальную среду сценарии активации, соответствующие платформе.
- upgrade_dependencies(context)¶
Обновляет основные пакеты зависимостей venv (в настоящее время
pip
) в окружении. Это делается путем перехода к исполняемому файлуpip
в окружении.Added in version 3.9.
Изменено в версии 3.12:
setuptools
больше не является зависимостью от ядра venv.
- post_setup(context)¶
Метод-заполнитель, который может быть переопределен в сторонних реализациях для предварительной установки пакетов в виртуальную среду или выполнения других действий после создания.
Изменено в версии 3.7.2: Теперь Windows использует скрипты перенаправления для
python[w].exe
вместо копирования фактических двоичных файлов. В 3.7.2 толькоsetup_python()
ничего не делает, если не запускается из сборки в дереве исходных текстов.Изменено в версии 3.7.3: Windows копирует скрипты перенаправления как часть
setup_python()
вместоsetup_scripts()
. В версии 3.7.2 это было не так. При использовании симлинков исходные исполняемые файлы будут слинкованы.Кроме того,
EnvBuilder
предоставляет этот метод, который может быть вызван изsetup_scripts()
илиpost_setup()
в подклассах для помощи в установке пользовательских скриптов в виртуальную среду.- install_scripts(context, path)¶
path - это путь к каталогу, который должен содержать подкаталоги «common», «posix», «nt», каждый из которых содержит скрипты, предназначенные для каталога bin в окружении. Содержимое каталога «common» и каталога, соответствующего
os.name
, копируется после некоторой текстовой замены заполнителей:__VENV_DIR__
заменяется на абсолютный путь к каталогу окружения.__VENV_NAME__
заменяется на имя окружения (конечный сегмент пути к каталогу окружения).__VENV_PROMPT__
заменяется на запрос (имя среды в круглых скобках и с последующим пробелом)__VENV_BIN_NAME__
заменяется именем каталога bin (либоbin
, либоScripts
).__VENV_PYTHON__
заменяется на абсолютный путь к исполняемому файлу среды.
Каталоги могут существовать (для случаев, когда обновляется существующая среда).
- create_git_ignore_file(context)¶
Создает
.gitignore
файл в виртуальном окружении, из-за чего весь каталог игнорируетсяgit
менеджером контроля исходных текстов.Added in version 3.13.
Также имеется функция удобства на уровне модуля:
- venv.create(env_dir, system_site_packages=False, clear=False, symlinks=False, with_pip=False, prompt=None, upgrade_deps=False, *, scm_ignore_files=frozenset())¶
Создайте
EnvBuilder
с заданными ключевыми аргументами и вызовите его методcreate()
с аргументом env_dir.Added in version 3.3.
Изменено в версии 3.4: Добавлен параметр
with_pip
Изменено в версии 3.6: Добавлен параметр
prompt
Изменено в версии 3.9: Добавлен параметр
upgrade_deps
Изменено в версии 3.13: Добавлен параметр
scm_ignore_files
Пример расширения EnvBuilder
¶
Следующий сценарий показывает, как расширить EnvBuilder
, реализовав подкласс, который устанавливает setuptools и pip в созданную виртуальную среду:
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):
"""
This builder installs setuptools and pip so that you can pip or
easy_install other packages into the created virtual environment.
:param nodist: If true, setuptools and pip are not installed into the
created virtual environment.
:param nopip: If true, pip is not installed into the created
virtual environment.
:param progress: If setuptools or pip are installed, the progress of the
installation can be monitored by passing a progress
callable. If specified, it is called with two
arguments: a string indicating some progress, and a
context indicating where the string is coming from.
The context argument can have one of three values:
'main', indicating that it is called from virtualize()
itself, and 'stdout' and 'stderr', which are obtained
by reading lines from the output streams of a subprocess
which is used to install the app.
If a callable is not specified, default progress
information is output to 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):
"""
Set up any packages which need to be pre-installed into the
virtual environment being created.
:param context: The information for the virtual environment
creation request being processed.
"""
os.environ['VIRTUAL_ENV'] = context.env_dir
if not self.nodist:
self.install_setuptools(context)
# Can't install pip without setuptools
if not self.nopip and not self.nodist:
self.install_pip(context)
def reader(self, stream, context):
"""
Read lines from a subprocess' output stream and either pass to a progress
callable (if specified) or write progress information to sys.stderr.
"""
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)
# Download script into the virtual environment's binaries folder
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()
# Install in the virtual environment
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')
# Clean up - no longer needed
os.unlink(distpath)
def install_setuptools(self, context):
"""
Install setuptools in the virtual environment.
:param context: The information for the virtual environment
creation request being processed.
"""
url = "https://bootstrap.pypa.io/ez_setup.py"
self.install_script(context, 'setuptools', url)
# clear up the setuptools archive which gets downloaded
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):
"""
Install pip in the virtual environment.
:param context: The information for the virtual environment
creation request being processed.
"""
url = 'https://bootstrap.pypa.io/get-pip.py'
self.install_script(context, 'pip', url)
def main(args=None):
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)
Этот скрипт также доступен для скачивания online.