venv — 虚拟环境创建

在 3.3 版本中添加。

源代码： Lib/venv/

---

venv 模块支持创建轻量级的“虚拟环境”，每个环境在各自的 site 目录中安装了独立的 Python 软件包集。虚拟环境是在现有 Python 安装（称为虚拟环境的“基础”Python）之上创建的，并且可以选择将其与基础环境中的软件包隔离，因此只有在虚拟环境中明确安装的软件包才可用。

在虚拟环境中使用时，pip 等常见安装工具会将 Python 软件包安装到虚拟环境中，而无需明确告知其这样做。

虚拟环境（除其他外）

• 用于包含特定 Python 解释器以及支持项目（库或应用程序）所需的软件库和二进制文件。这些默认情况下与其他虚拟环境中的软件以及操作系统中安装的 Python 解释器和库隔离。

• 包含在目录中，通常在项目目录中命名为 venv 或 .venv，或在大量虚拟环境的容器目录下，例如 ~/.virtualenvs。

• 不会检入到 Git 等源代码控制系统中。

• 被视为一次性的 - 删除并从头开始重新创建它应该很简单。不要将任何项目代码放在环境中

• 不被视为可移动或可复制的 - 只需在目标位置重新创建相同的环境。

请参阅 PEP 405 以了解有关 Python 虚拟环境的更多背景信息。

另请参阅

Python 打包用户指南：创建和使用虚拟环境

可用性：Emscripten 不支持，WASI 不支持。

此模块在 WebAssembly 平台 wasm32-emscripten 和 wasm32-wasi 上不起作用或不可用。有关更多信息，请参阅 WebAssembly 平台。

创建虚拟环境

通过执行命令 venv 来创建 虚拟环境。

python -m venv /path/to/new/virtual/environment

运行此命令将创建目标目录（创建尚未存在的任何父目录），并在其中放置一个 pyvenv.cfg 文件，其中包含一个 home 键，指向运行命令的 Python 安装（目标目录的常用名称是 .venv）。它还创建一个 bin（或在 Windows 上为 Scripts）子目录，其中包含 Python 二进制文件/二进制文件的副本/符号链接（根据环境创建时使用的平台或参数而定）。它还创建一个（最初为空的）lib/pythonX.Y/site-packages 子目录（在 Windows 上，这是 Lib\site-packages）。如果指定了现有目录，则将重新使用该目录。

3.5 版中已更改： 现在建议使用 venv 来创建虚拟环境。

自 3.6 版起已弃用： pyvenv 是为 Python 3.3 和 3.4 创建虚拟环境的推荐工具，并且 已在 Python 3.6 中弃用。

在 Windows 上，按如下方式调用 venv 命令

c:\>Python35\python -m venv c:\path\to\myenv

或者，如果您为 Python 安装 配置了 PATH 和 PATHEXT 变量

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]
            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) 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.12 版中已更改： setuptools 不再是核心 venv 依赖项。

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

有关更多信息，请参见 关于执行策略。

创建的 pyvenv.cfg 文件还包括 include-system-site-packages 键，如果使用 --system-site-packages 选项运行 venv，则设置为 true，否则设置为 false。

除非给出了 --without-pip 选项，否则将调用 ensurepip 将 pip 引导到虚拟环境中。

可以向 venv 提供多条路径，在这种情况下，将根据给定的选项在每个提供的路径处创建相同的虚拟环境。

venv 的工作原理

当 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	$ source <venv>/bin/activate
	fish	$ source <venv>/bin/activate.fish
	csh/tcsh	$ source <venv>/bin/activate.csh
	PowerShell	$ <venv>/bin/Activate.ps1
Windows	cmd.exe	C:\> <venv>\Scripts\activate.bat
	PowerShell	PS C:\> <venv>\Scripts\Activate.ps1

3.4 版中新增： fish 和 csh 激活脚本。

3.8 版中新增： 为支持 PowerShell Core 在 POSIX 下安装 PowerShell 激活脚本。

你不需要专门激活虚拟环境，因为你可以在调用 Python 时指定该环境的 Python 解释器的完整路径。此外，环境中安装的所有脚本都可以在不激活环境的情况下运行。

为了实现这一点，安装在虚拟环境中的脚本有一个指向环境的 Python 解释器的“shebang”行，即 #!/<path-to-venv>/bin/python。这意味着脚本将使用该解释器运行，而不管 PATH 的值如何。在 Windows 上，如果你安装了 适用于 Windows 的 Python 启动器，则支持“shebang”行处理。因此，在 Windows 资源管理器窗口中双击已安装脚本应该使用正确的解释器运行它，而无需激活环境或在 PATH 中。

激活虚拟环境后， VIRTUAL_ENV 环境变量将被设置为环境的路径。由于不需要显式激活虚拟环境来使用它，因此不能依赖 VIRTUAL_ENV 来确定是否正在使用虚拟环境。

警告

由于安装在环境中的脚本不应该期望环境被激活，因此它们的 shebang 行包含它们环境的解释器的绝对路径。因此，在一般情况下，环境本质上是不可移植的。你应该始终有简单的方法来重新创建环境（例如，如果你有一个需求文件 requirements.txt，你可以调用 pip install -r requirements.txt 使用环境的 pip 来安装环境所需的所有包）。如果你出于任何原因需要将环境移动到新位置，你应该在所需位置重新创建它，并删除旧位置中的环境。如果你移动环境是因为你移动了它的父目录，你应该在它的新位置重新创建环境。否则，安装在环境中的软件可能无法按预期工作。

你可以通过在 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)

在实例化时，EnvBuilder 类接受以下关键字参数

• system_site_packages – 布尔值，表示系统 Python 站点包应可用于环境（默认为 False）。

• clear – 布尔值，如果为真，将在创建环境之前删除任何现有目标目录的内容。

• symlinks – 布尔值，表示是否尝试符号链接 Python 二进制文件，而不是复制。

• upgrade – 布尔值，如果为真，将使用正在运行的 Python 升级现有环境 - 用于在该 Python 已就地升级时（默认为 False）。

• with_pip – 布尔值，如果为真，确保 pip 已安装在虚拟环境中。这使用 ensurepip 和 --default-pip 选项。

• prompt – 激活虚拟环境后要使用的字符串（默认为 None，表示将使用环境的目录名称）。如果提供了特殊字符串 "."，则使用当前目录的基础名称作为提示符。

• upgrade_deps – 将基本 venv 模块更新到 PyPI 上的最新模块

在 3.4 版本中更改： 添加 with_pip 参数

在 3.6 版本中更改： 添加 prompt 参数

在 3.9 版本中更改： 添加 upgrade_deps 参数

第三方虚拟环境工具的创建者可以自由使用提供的 EnvBuilder 类作为基类。

返回的 env-builder 是一个对象，它有一个方法 create

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)

创建环境目录和所有必要的子目录（如果不存在），并返回一个上下文对象。此上下文对象只是一个属性（例如路径）的持有者，供其他方法使用。如果 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 - 虚拟环境的 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 版中已更改： venv 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 可执行文件发出 shell 命令来完成此操作。

在 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__ 被环境可执行文件的绝对路径替换。

允许目录存在（用于升级现有环境时）。

还有一个模块级便利函数

venv.create(env_dir, system_site_packages=False, clear=False, symlinks=False, with_pip=False, prompt=None, upgrade_deps=False)

使用给定的关键字参数创建一个 EnvBuilder，并使用 env_dir 参数调用其 create() 方法。

在 3.3 版本中添加。

在 3.4 版本中更改： 添加 with_pip 参数

在 3.6 版本中更改： 添加 prompt 参数

在 3.9 版本中更改： 添加 upgrade_deps 参数

扩展 EnvBuilder 的示例

以下脚本展示了如何通过实现一个将 setuptools 和 pip 安装到创建的虚拟环境中的子类来扩展 EnvBuilder

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)

此脚本也可在线下载 在线。