venv — 创建虚拟环境

3.3 版本新增。

源代码： Lib/venv/

---

venv 模块支持创建轻量级的“虚拟环境”，每个环境都有自己独立的 Python 包集合，这些包安装在它们的 site 目录中。虚拟环境是在现有 Python 安装的基础上创建的，称为虚拟环境的“基础”Python，并且可以选择与基础环境中的包隔离，因此只有那些明确安装在虚拟环境中的包才可用。

当在虚拟环境中使用时，诸如 pip 之类的常用安装工具会将 Python 包安装到虚拟环境中，而无需明确告知这样做。

虚拟环境（除其他事项外）是：

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

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

• 不检查到诸如 Git 之类的源代码控制系统中。

• 被认为是可丢弃的 - 从头开始删除和重新创建它应该很简单。您不会将任何项目代码放在环境中。

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

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

另请参阅

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

可用性：不是 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 上，这是 Libsite-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.

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-files
                        Skips adding SCM ignore files to the environment
                        directory (Git is supported 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 选项。

在 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 键，如果使用 --system-site-packages 选项运行 venv，则设置为 true，否则设置为 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 就足以确定当前解释器是否正在从虚拟环境运行。

可以使用其二进制目录（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
	pwsh	$ <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 版本新增: 在 POSIX 下安装 PowerShell 激活脚本以支持 PowerShell Core。

你并非必须激活虚拟环境，因为你可以在调用 Python 时直接指定该环境的 Python 解释器的完整路径。此外，所有安装在环境中的脚本都应该无需激活即可运行。

为了实现这一点，安装到虚拟环境中的脚本都有一行 “shebang” 行，指向环境的 Python 解释器，如 #!/<虚拟环境路径>/bin/python。这意味着脚本将使用该解释器运行，而不管 PATH 的值如何。在 Windows 上，如果你安装了 适用于 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。 这会使用带有 --default-pip 选项的 ensurepip。

• 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 版本中变更: 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 可执行文件来实现的。

在 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() 的一部分进行复制，而不是 setup_scripts()。这在 3.7.2 中并非如此。当使用符号链接时，将链接原始可执行文件。

还有一个模块级别的便捷函数

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，并使用 env_dir 参数调用其 create() 方法。

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)

此脚本也可 在线 下载。