# `venv` --- 虚拟环境的创建

Added in version 3.3.

源码： Lib/venv/

`venv` 模块支持创建轻量的“虚拟环境”，每个虚拟环境将拥有它们自己独立的安装在其 `site` 目录中的 Python 软件包集合。 虚拟环境是在现有的 Python 安装版基础之上创建的，这被称为虚拟环境的“基础”Python，并且默认与基础环境中的软件包隔离开来，这样只有在虚拟环境中显式安装的软件包才是可用的。 有关更多信息，请参阅 虚拟环境 和 `site` 的 虚拟环境文档。

当在虚拟环境中使用时，常见安装工具如 pip 将把 Python 软件包安装到虚拟环境而无需显式地指明这一点。

虚拟环境是（主要的特性）：

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

- 包含在一个目录中，根据惯例被命名为项目目录下的 `.venv` 或 `venv`，或是有许多虚拟环境的容器目录下，如 `~/.virtualenvs`。

- 不可签入 Git 等源代码控制系统。

- 被认为是可丢弃的 -- 它应当能被简单地删除并从头开始重建。 你不应在此环境中放置任何项目代码。

- 不被视为是可移动或可复制的 —— 你只能在目标位置重建相同的环境。

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

参见

Python Packaging User Guide: Creating and using virtual environments

Availability: not Android, not iOS, not 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` 来创建虚拟环境。

Deprecated since version 3.6, removed in version 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

参阅 About Execution Policies 以获取更多信息。

创建的 `pyvenv.cfg` 文件还包括 `include-system-site-packages` 键，如果运行 `venv` 时带有 `--system-site-packages` 选项则将会其设为 `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`

Added in version 3.4: fish 和 csh 激活脚本。

Added in version 3.8: 在 POSIX 上安装 PowerShell 激活脚本，以支持 PowerShell Core。

激活一个虚拟环境的操作 不是必需的，因为你完全可以在唤起 Python 时指明特定虚拟环境的 Python 解释器的完整路径。 更进一步地说，安装在虚拟环境中的所有脚本也都可以在不激活该虚拟环境的情况下运行。

为了达成此目的，安装到虚拟环境中的脚本将包含一个以“井号叹号”打头的行用来指定虚拟环境的 Python 解释器，`#!/<path-to-venv>/bin/python`。 这意味着无论 `PATH` 的值是什么该脚本都将使用指定的解释器运行。 在 Windows 上，对处理“井号叹号”行的支持将在你安装了 Python 安装管理器 的情况下获得。 这样，在 Windows 资源管理器窗口中双击一个已安装的脚本应当会使用正确的解释器运行它而无需激活相应虚拟环境或设置 `PATH`。

当一个虚拟环境已被激活时，`VIRTUAL_ENV` 环境变量会被设为该虚拟环境的路径。 由于使用虚拟环境并不需要显式地激活它，因此 `VIRTUAL_ENV` 并不能被用来可靠地确定是否正在使用虚拟环境。

警告

因为安装在虚拟环境中的脚本不应要求必须激活该虚拟环境，所以它们的“井号叹号”行会包含虚拟环境的绝对路径。 因为这一点，所以虚拟环境在通常情况下都是不可移植的。 你应当保证提供重建一个虚拟环境的简便方式（举例来说，如果你准备了需求文件 `requirements.txt`，则可以使用虚拟环境的 `pip` 执行 `pip install -r requirements.txt` 来安装虚拟环境所需的所有软件包）。 如果出于某种原因你需要将虚拟环境移动到一个新的位置，则你应当在目标位置上重建它并删除旧位置上的虚拟环境。 如果出于某种原因你移动了一个虚拟环境的上级目录，你也应当在新位置上重建该虚拟环境。 否则，安装到该虚拟环境的软件包可能无法正常工作。

你可以通过在 shell 中输入 `deactivate` 来取消激活一个虚拟环境。 取消激活的实现机制依赖于具体平台并且属于内部实现细节（通常，将会使用一个脚本或者 shell 函数）。

## API

上述的高级方法使用了一个简单的 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 -- 一个布尔值，当为真时，将在创建环境前删除任何现有目标目录的内容。

  - symlinks -- 一个指明是否要尝试创建 Python 二进制文件的符号链接而非复制的布尔值。

  - upgrade -- 一个布尔值，当为真时，将使用当前运行的 Python 升级现有环境 —— 用于 Python 已原地更新的情况 (默认为 `False`)。

  - with_pip -- 一个布尔值，当为真时，将确保在虚拟环境中已安装 pip。 这将执行 `ensurepip` 并使用 `--default-pip` 选项。

  - prompt -- 一个要在虚拟环境被激活后显示的字符串（默认值 `None` 表示将使用环境的目录名）。 如果提供特殊的字符串 `"."`，则将使用当前目录的基本名作为提示符。

  - upgrade_deps -- 将 venv 的基础模块更新为 PyPI 上的最新版本

  - scm_ignore_files -- 基于在可迭代对象中指定的源代码控制管理器（SCM）创建忽略文件。 这项支持是通过名为 `create_{scm}_ignore_file` 的方法来定义的。 默认支持的值只有通过 `create_git_ignore_file()` 定义的 `"git"`。

  在 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):
            """
            在一个目录中创建虚拟的 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()`, `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` - 虚拟环境的 script 路径。

    - `bin_name` - 相对于虚拟环境位置的 script 路径名称。 用于激活脚本中的 `__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)。 这是通过将 shell 命令传出到环境中的 `pip` 可执行文件来完成的。

    Added in version 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 源代码控制管理器所忽略。

    Added in version 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()` 方法。

  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)
            # 没有 setuptools 无法安装 pip
            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)
            # 将脚本下载到虚拟环境的可执行文件目录
            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):
            """
            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)
            # 清理已下载的 setuptools 归档
            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)

这个脚本同样可以 在线下载。