venv — 创建虚拟环境¶
在 3.3 版本加入。
源代码: Lib/venv/
venv 模块支持创建轻量级的“虚拟环境”，每个虚拟环境都有自己独立的 Python 包集，这些包安装在它们的 site 目录中。虚拟环境是基于现有的 Python 安装创建的，这个安装被称为虚拟环境的“基础” Python。默认情况下，它与基础环境中的包是隔离的，因此只有明确安装在虚拟环境中的包才可用。有关更多信息，请参阅 虚拟环境 和 site 的 虚拟环境文档。
当从虚拟环境内部使用时，像 pip 这样的常用安装工具将把 Python 包安装到虚拟环境中，而无需显式告知。
虚拟环境（除其他外）是：
用于包含特定 Python 解释器以及支持项目（库或应用程序）所需的软件库和二进制文件。默认情况下，它们与来自其他虚拟环境的软件以及安装在操作系统上的 Python 解释器和库是隔离的。
包含在一个目录中，通常在项目目录中命名为
.venv或venv，或者在一个用于存放大量虚拟环境的容器目录中，例如~/.virtualenvs。不纳入 Git 等源代码控制系统。
被视为一次性的——删除并从头开始重新创建它应该是简单的。您不应将任何项目代码放入环境中。
不被视为可移动或可复制——您只需在目标位置重新创建相同的环境。
有关 Python 虚拟环境的更多背景信息，请参阅 PEP 405。
可用性: 非 Android、非 iOS、非 WASI。
该模块在移动平台或WebAssembly 平台上不受支持。
创建虚拟环境¶
通过执行 venv 模块来创建 虚拟环境。
python -m venv /path/to/new/virtual/environment
这会创建目标目录（包括必要的父目录），并在其中放置一个 pyvenv.cfg 文件，其中包含一个指向运行该命令的 Python 安装的 home 键。它还会创建一个 bin（在 Windows 上是 Scripts）子目录，其中包含 Python 可执行文件的副本或符号链接（根据平台或创建环境时使用的参数而定）。它还创建一个 lib/pythonX.Y/site-packages 子目录（在 Windows 上是 Lib\site-packages）。如果指定了现有目录，它将被重新使用。
已在 3.5 版本中更改： 现在推荐使用 venv 来创建虚拟环境。
已弃用，从 3.6 版本开始，将在 3.8 版本中删除： pyvenv 是 Python 3.3 和 3.4 版本创建虚拟环境的推荐工具，并在 3.5 版本中被直接执行 venv 所取代。
在 Windows 上，请按以下方式调用 venv 命令
PS> python -m venv C:\path\to\new\virtual\environment
如果使用 -h 运行该命令，它将显示可用的选项。
usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear]
[--upgrade] [--without-pip] [--prompt PROMPT] [--upgrade-deps]
[--without-scm-ignore-files]
ENV_DIR [ENV_DIR ...]
Creates virtual Python environments in one or more target directories.
Once an environment has been created, you may wish to activate it, e.g. by
sourcing an activate script in its bin directory.
- ENV_DIR¶
一个必需参数，指定要创建环境的目录。
- --system-site-packages¶
允许虚拟环境访问系统 site-packages 目录。
- --symlinks¶
在符号链接不是平台默认设置时，尝试使用符号链接而不是复制。
- --copies¶
即使符号链接是平台的默认设置，也尝试使用复制而不是符号链接。
- --clear¶
如果环境目录已存在，则在创建环境之前删除其内容。
- --upgrade¶
将环境目录升级到使用此版本的 Python，前提是 Python 已就地升级。
- --without-pip¶
跳过在虚拟环境中安装或升级 pip（pip 默认会被引导安装）。
- --prompt <PROMPT>¶
为该环境提供一个替代的提示符前缀。
- --upgrade-deps¶
将核心依赖项（pip）升级到 PyPI 中的最新版本。
- --without-scm-ignore-files¶
跳过将 SCM 忽略文件添加到环境目录（默认支持 Git）。
已在 3.4 版本中更改： 默认安装 pip，并添加了 --without-pip 和 --copies 选项。
已在 3.4 版本中更改： 在早期版本中，如果目标目录已存在，则会引发错误，除非提供了 --clear 或 --upgrade 选项。
已在 3.9 版本中更改： 添加了 --upgrade-deps 选项，用于将 pip 和 setuptools 升级到 PyPI 中的最新版本。
已在 3.12 版本中更改： setuptools 不再是 venv 的核心依赖项。
已在 3.13 版本中更改： 添加了 --without-scm-ignore-files 选项。
已在 3.13 版本中更改： venv 现在默认创建一个用于 Git 的 .gitignore 文件。
备注
虽然 Windows 支持符号链接，但**不推荐**使用。特别需要注意的是，在文件资源管理器中双击 python.exe 会立即解析符号链接并忽略虚拟环境。
备注
在 Microsoft Windows 上，可能需要通过设置用户的执行策略来启用 Activate.ps1 脚本。您可以通过发出以下 PowerShell 命令来完成此操作：
PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
有关更多信息，请参阅 关于执行策略。
创建的 pyvenv.cfg 文件还包含 include-system-site-packages 键，如果 venv 使用 --system-site-packages 选项运行，则设置为 true，否则设置为 false。
除非提供了 --without-pip 选项，否则将调用 ensurepip 来引导 pip 到虚拟环境中。
可以向 venv 提供多个路径，在这种情况下，将根据给定的选项在每个提供的路径上创建一个相同的虚拟环境。
Venvs 的工作原理¶
当 Python 解释器在虚拟环境中运行时，sys.prefix 和 sys.exec_prefix 指向虚拟环境的目录，而 sys.base_prefix 和 sys.base_exec_prefix 指向用于创建环境的基础 Python 的目录。检查 sys.prefix != sys.base_prefix 以确定当前解释器是否在虚拟环境中运行就足够了。
可以使用其二进制目录（POSIX 上为 bin；Windows 上为 Scripts）中的脚本来“激活”虚拟环境。这将把该目录添加到 PATH 的前面，这样运行 python 将调用环境的 Python 解释器，并且您可以运行已安装的脚本，而无需使用其完整路径。激活脚本的调用是平台特定的（<venv> 必须替换为包含虚拟环境的目录的路径）：
平台 |
Shell |
激活虚拟环境的命令 |
|---|---|---|
POSIX |
bash/zsh |
|
fish |
|
|
csh/tcsh |
|
|
pwsh |
|
|
Windows |
cmd.exe |
|
PowerShell |
|
已在 3.4 版本中添加： fish 和 csh 激活脚本。
已在 3.8 版本中添加： PowerShell 激活脚本在 POSIX 下安装，以支持 PowerShell Core。
您并不需要特别**激活**虚拟环境，因为您可以在调用 Python 时直接指定该环境的 Python 解释器的完整路径。此外，环境中安装的所有脚本都应该能够无需激活即可运行。
为了实现这一点，安装到虚拟环境中的脚本会有一个指向环境 Python 解释器的“shebang”行，格式为 #!/<path-to-venv>/bin/python。这意味着脚本将使用该解释器运行，而与 PATH 的值无关。在 Windows 上，如果您安装了 Python 安装管理器，则支持“shebang”行处理。因此，在 Windows 文件资源管理器中双击已安装的脚本应该可以使用正确的解释器运行它，而无需激活环境或将其添加到 PATH。
当虚拟环境被激活时，VIRTUAL_ENV 环境变量会被设置为环境的路径。由于使用虚拟环境不需要显式激活它，因此不能依赖 VIRTUAL_ENV 来确定是否正在使用虚拟环境。
警告
由于环境中安装的脚本不应期望环境被激活，因此它们的 shebang 行包含指向其环境解释器的绝对路径。因此，在一般情况下，环境本身在本质上是不可移植的。您应该始终有一个简单的重现环境的方法（例如，如果您有一个 requirements 文件 requirements.txt，您可以使用环境的 pip 调用 pip install -r requirements.txt 来安装环境中所有必需的包）。如果由于任何原因您需要将环境移动到新位置，您应该在新位置重新创建它，并删除旧位置的环境。如果您移动环境是因为移动了其父目录，您应该在新位置重新创建环境。否则，安装到环境中的软件可能无法按预期工作。
您可以通过在 shell 中键入 deactivate 来停用虚拟环境。具体机制是平台相关的，并且是内部实现细节（通常会使用脚本或 shell 函数）。
API¶
上面描述的高级方法使用了简单的 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-packages 是否应可用于环境（默认为
False）。clear – 一个布尔值，如果为 true，则在创建环境之前，将删除任何现有目标目录的内容。
symlinks – 一个布尔值，指示是否尝试链接 Python 二进制文件而不是复制。
upgrade – 一个布尔值，如果为 true，将使用运行中的 Python 升级现有环境——用于 Python 已就地升级的情况（默认为
False）。with_pip – 一个布尔值，如果为 true，则确保 pip 已安装在虚拟环境中。这使用
ensurepip和--default-pip选项。prompt – 在虚拟环境激活后使用的字符串（默认为
None，这意味着环境的目录名称将被用作提示符）。如果提供了特殊字符串"."，则使用当前目录的基名称作为提示符。upgrade_deps – 将基础 venv 模块更新到 PyPI 中的最新版本。
scm_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可用作基类。- create(env_dir)¶
通过指定要包含虚拟环境的目标目录（绝对路径或相对于当前目录），来创建虚拟环境。
create方法将要么在指定目录中创建环境，要么引发适当的异常。EnvBuilder类的create方法说明了可用于子类自定义的钩子：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)¶
创建环境目录和所有必需的尚不存在的子目录，并返回一个上下文对象。此上下文对象仅用于保存供其他方法使用的属性（如路径）。如果使用
clear=True参数创建EnvBuilder，则将清除环境目录的内容，然后重新创建所有必需的子目录。返回的上下文对象是
types.SimpleNamespace，具有以下属性：env_dir- 虚拟环境的位置。用于激活脚本中的__VENV_DIR__（请参阅install_scripts()）。env_name- 虚拟环境的名称。用于激活脚本中的__VENV_NAME__（请参阅install_scripts()）。prompt- 激活脚本使用的提示符。用于激活脚本中的__VENV_PROMPT__（请参阅install_scripts()）。executable- 虚拟环境使用的底层 Python 可执行文件。这会考虑到从另一个虚拟环境创建虚拟环境的情况。inc_path- 虚拟环境的 include 路径。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 版本中更改： 使用 sysconfig 安装方案 来构建创建目录的路径。
已在 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可执行文件来完成的。在 3.9 版本中新增。
已在 3.12 版本中更改： setuptools 不再是 venv 的核心依赖项。
- post_setup(context)¶
一个占位符方法，可以在第三方实现中覆盖，用于预先安装包到虚拟环境中或执行其他创建后的步骤。
- install_scripts(context, path)¶
可以在子类中的
setup_scripts()或post_setup()中调用此方法，以协助将自定义脚本安装到虚拟环境中。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 源代码控制管理器忽略。在 3.13 版本加入。
已在 3.7.2 版本中更改： Windows 现在使用重定向脚本来处理
python[w].exe，而不是复制实际的二进制文件。在 3.7.2 版本中，只有setup_python()在从源代码树的构建中运行时才执行任何操作。已在 3.7.3 版本中更改： Windows 将重定向脚本作为
setup_python()的一部分进行复制，而不是像 3.7.2 版本那样在setup_scripts()中进行。使用符号链接时，将链接原始可执行文件。
还有一个模块级别的便捷函数：
- 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 参数。在 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)
此脚本也可 在线 下载。