venv — 创建虚拟环境

3.3 版中的新功能。

源代码： :source:`Lib/venv/`

venv 模块支持创建具有自己站点目录的轻量级“虚拟环境”，可选择与系统站点目录隔离。每个虚拟环境都有自己的 Python 二进制文件（它与用于创建此环境的二进制文件的版本相匹配），并且可以在其站点目录中拥有自己独立的一组已安装的 Python 包。

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

也可以看看

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

创建虚拟环境

虚拟环境的创建是通过执行命令venv来完成的：

python3 -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.6 版起已弃用：pyvenv 是为 Python 3.3 和 3.4 创建虚拟环境的推荐工具，在 Python 3.6 中已弃用。

3.5 版更改：现在推荐使用 venv 来创建虚拟环境。

在 Windows 上，调用 venv 命令如下：

c:\>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 setuptools 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.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 键，如果 venv 与 --system-site-packages 选项一起运行，则设置为 true，false 否则。

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

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

一旦创建了虚拟环境，就可以使用虚拟环境二进制目录中的脚本“激活”它。脚本的调用是特定于平台的 ( 必须替换为包含虚拟环境的目录的路径）：

平台	贝壳	激活虚拟环境的命令
POSIX	bash/zsh	$ 来源 /bin/激活
	鱼	$ 来源 /bin/activate.fish
	csh/tcsh	$ 来源 /bin/activate.csh
	PowerShell 核心	$ /bin/Activate.ps1
视窗	命令行工具	C:\> \Scripts\activate.bat
	电源外壳	PS C:\> \Scripts\Activate.ps1

当虚拟环境处于活动状态时，VIRTUAL_ENV 环境变量设置为虚拟环境的路径。这可用于检查是否在虚拟环境中运行。

你不需要需要来激活环境；激活只是将虚拟环境的二进制目录添加到您的路径中，以便“python”调用虚拟环境的 Python 解释器，您可以运行已安装的脚本而无需使用它们的完整路径。但是，安装在虚拟环境中的所有脚本都应该可以在不激活的情况下运行，并自动与虚拟环境的 Python 一起运行。

您可以通过在 shell 中键入“deactivate”来停用虚拟环境。确切的机制是特定于平台的，并且是内部实现细节（通常将使用脚本或 shell 函数）。

3.4 新功能：fish 和 csh 激活脚本。

3.8 版新功能：PowerShell 激活脚本安装在 POSIX 下以支持 PowerShell Core。

笔记

虚拟环境是一种 Python 环境，其中安装的 Python 解释器、库和脚本与安装在其他虚拟环境中的那些隔离，并且（默认情况下）安装在“系统”Python 中的任何库，即安装的库和脚本作为操作系统的一部分。

虚拟环境是一个目录树，其中包含 Python 可执行文件和其他表明它是虚拟环境的文件。

setuptools 和 pip 等常用安装工具在虚拟环境中按预期工作。换句话说，当虚拟环境处于活动状态时，他们将 Python 包安装到虚拟环境中，而无需明确告知这样做。

当虚拟环境处于活动状态时（即虚拟环境的 Python 解释器正在运行），属性 sys.prefix 和 sys.exec_prefix 指向虚拟环境的基目录，而sys.base_prefix 和 sys.base_exec_prefix 指向用于创建虚拟环境的非虚拟环境 Python 安装。如果虚拟环境未激活，则 sys.prefix 与 sys.base_prefix 相同，而 sys.exec_prefix 与 sys 相同。 base_exec_prefix（它们都指向非虚拟环境 Python 安装）。

当虚拟环境处于活动状态时，所有 distutils 配置文件中的任何更改安装路径的选项都将被忽略，以防止项目被无意中安装到虚拟环境之外。

在命令 shell 中工作时，用户可以通过在虚拟环境的可执行文件目录中运行 activate 脚本（精确的文件名和使用该文件的命令取决于 shell）来激活虚拟环境，该脚本在虚拟环境的前面加上将可执行文件的环境目录添加到正在运行的 shell 的 PATH 环境变量中。在其他情况下应该不需要激活虚拟环境；安装到虚拟环境中的脚本有一个“shebang”行，它指向虚拟环境的 Python 解释器。这意味着无论 PATH 的值如何，脚本都将与该解释器一起运行。在 Windows 上，如果您安装了适用于 Windows 的 Python Launcher，则支持“shebang”行处理（这已在 3.3 中添加到 Python 中 - 有关更多详细信息，请参阅 PEP 397）。因此，在 Windows 资源管理器窗口中双击已安装的脚本应该使用正确的解释器运行脚本，而无需在 PATH 中引用其虚拟环境。

应用程序接口

上述高级方法使用了一个简单的 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): 创建环境目录和所有必需的目录，并返回一个上下文对象。这只是属性（例如路径）的持有者，供其他方法使用。允许目录已经存在，只要指定 clear 或 upgrade 以允许在现有环境目录上进行操作。

create_configuration(context): 在环境中创建 pyvenv.cfg 配置文件。

setup_python(context): 在环境中创建 Python 可执行文件的副本或符号链接。在 POSIX 系统上，如果使用了特定的可执行文件 python3.x，则将创建指向该可执行文件的 python 和 python3 的符号链接，除非具有这些名称的文件已经存在。

setup_scripts(context): 将适用于平台的激活脚本安装到虚拟环境中。

upgrade_dependencies(context): 升级环境中的核心venv依赖包（目前为pip和setuptools）。这是通过外壳到环境中的 pip 可执行文件来完成的。

3.9 版中的新功能。

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://bitbucket.org/pypa/setuptools/downloads/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):
    compatible = True
    if sys.version_info < (3, 3):
        compatible = False
    elif not hasattr(sys, 'base_prefix'):
        compatible = False
    if not compatible:
        raise ValueError('This script is only for use with '
                         'Python 3.3 or later')
    else:
        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)

该脚本也可用于下载在线。

venv — 创建虚拟环境 — Python 文档

venv — 创建虚拟环境

创建虚拟环境

应用程序接口

扩展EnvBuilder的例子