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)

此指令碼也可 線上 下載。