# `venv` --- 建立虛擬環境

在 3.3 版被加入.

原始碼：Lib/venv/

`venv` 模組支援建立輕量級的「虛擬環境」，每個虛擬環境都有獨立安裝在其 `site` 目錄中的一組 Python 套件。虛擬環境是建立在既有的 Python 安裝上（稱為該虛擬環境的「基底」Python）之上，預設會與基底環境中的套件隔離，使得僅能存取明確安裝在虛擬環境中的套件。更多資訊請參閱 虛擬環境 以及 `site` 的虛擬環境文件。

在使用虛擬環境中時，像 pip 這樣的常用安裝工具會自動將 Python 套件安裝至虛擬環境中，而不需要額外指定。

虛擬環境是（主要的特性）：

- 用來包含特定的 Python 直譯器、函式庫與二進位檔案，以支援某個專案（函式庫或應用程式）。預設情況下，這些內容會與其他虛擬環境中的軟體以及作業系統中安裝的 Python 直譯器與函式庫隔離。

- 被包含在一個目錄中，通常命名為專案目錄下的 `.venv` 或 `venv`，也可能是在用來管理多個虛擬環境的容器目錄中，例如 `~/.virtualenvs`。

- 不應提交至 Git 等版本控制系統。

- 被視為可拋棄的資源——應能簡單地刪除並從頭重新建立。請勿將任何專案程式碼放置於虛擬環境中。

- 不應移動或複製——若需在其他位置使用，應重新建立相同的虛擬環境。

更多關於 Python 虛擬環境的背景資訊請見 PEP 405。

也參考

Python 套件指南：建立與使用虛擬環境

可用性: 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` 來建立虛擬環境。

自從版本 3.6 後不推薦使用，已從版本 3.8 中移除。: pyvenv 是在 Python 3.3 和 3.4 中建立虛擬環境的推薦工具，但在 Python 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

  A required argument specifying the directory to create the environment in.

--system-site-packages

  Give the virtual environment access to the system site-packages directory.

--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).

在 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` 的鍵，如果使用 `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 時就會叫用該環境的直譯器並且執行已安裝的腳本，而不需要使用完整的路徑。啟動腳本的方式因平台而異（`<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 版被加入: PowerShell 的啟動腳本安裝在 POSIX 上支援 PowerShell Core。

你不用特別開啟虛擬環境，你可以在呼叫 Python 時指定該環境下 Python 直譯器的完整路徑。此外，所有安裝在環境裡的腳本都應該都可以在未啟用虛擬環境的情況下運行。

為了實現這一點，安裝在虛擬環境中的腳本會有一個 "shebang" 列，此列指向該環境的 Python 直譯器 `#!/<path-to-venv>/bin/python`。這代表無論 `PATH` 的值為何，該腳本都會在直譯器上運行。在 Windows 上，如果你安裝了 Python 安裝管理員，則支援 "shebang" 列處理。因此，在 Windows 檔案總管（Windows Explorer）中雙擊已安裝的腳本，應該可以在沒有啟用環境或將其加入 `PATH` 的情況下正確地運行。

當虛擬環境被啟用時，`VIRTUAL_ENV` 環境變數會被設置為該環境的路徑。由於不需要明確啟用虛擬環境才能使用它。因此，無法依賴 `VIRTUAL_ENV` 來判斷是否正在使用虛擬環境。

警告

因為安裝在環境中的腳本不應該預期該環境已經被啟動，所以它們的 shebang 列會包含環境直譯器的絕對路徑。因此，在一般情況下，環境本質上是不可攜帶的。你應該使用一個簡單的方法來重新建立一個環境（例如：如果你有一個名為 `requirements.txt` 的需求檔案，你可以使用環境的 `pip install -r requirements.txt` 來安裝環境所需的所有套件）。如果出於某種原因，你需要將環境移至新位置，你應該在所需位置重新建立它，並刪除舊位置的環境。如果你移動環境是因為移動了其父目錄，你應該在新位置重新建立環境。否則，安裝在該環境中的軟體可能無法正常運作。

你可以在 shell 輸入 `deactivate` 來關閉虛擬環境。具體的使用方式因平台而異，是內部實作的細節（通常會使用腳本或是 shell 函式）

## API

上述提到的高階 method（方法）透過簡單的 API 使用， 為第三方虛擬環境建立者提供可以依據他們需求來建立環境的客製化機制： `EnvBuilder` class。

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())

  進行實例化時，class `EnvBuilder` 接受下列的關鍵字引數：

  - system_site_packages -- 為一個 boolean （布林值），並表明系統的 Python site-packages 是否可以在環境中可用（預設為 `False` ）。

  - clear -- 為一個 boolean，如果為 true，則在建立環境之前，刪除目標目錄內所有存在的內容。

  - symlinks -- 為一個 boolean，並表明是否嘗試與 Python 二進位檔案建立符號連結而不是複製該檔案。

  - upgrade -- 為一個 boolean，若為 true，則會在執行 Python 時為現有的環境進行升級。目的是讓 Python 可以升級到位（預設為 `False`）。

  - with_pip -- 為一個 boolean，若為 true，則確保 pip 有安裝至虛擬環境之中。當有 `--default-pip` 的選項時，會使用 `ensurepip`。

  - prompt -- 為一個 String（字串），該字串會在虛擬環境啟動時被使用。（預設為 `None`，代表該環境的目錄名稱會被使用）倘若出現特殊字串 `"."` ，則目前目錄的 basename 會做為提示路徑使用。

  - 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` method 將會在指定的目錄下建立環境，或是觸發適當的例外。

    `EnvBuilder` class 的 `create` method 會闡述可用的 Hooks 以客製化 subclass （子類別）:

        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)

    每個 methods `ensure_directories()`、`create_configuration()`、`setup_python()`、`setup_scripts()` 及 `post_setup()` 都可以被覆寫。

  ensure_directories(env_dir)

    建立還不存在的環境目錄及必要的子目錄，並回傳一個情境物件（context object）。這個情境物件只是一個屬性 (例如：路徑) 的所有者，可被其他 method 使用。如果 `EnvBuilder` 已被建立且帶有 `clear=True` 的引數，該環境目錄下的內容將被清空，以及所有必要的子目錄將被重新建立。

    回傳的情境物件（context object）其型別會是 `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__` 會被替換為環境中 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 urlsplit
    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, _, _ = urlsplit(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)

此腳本也可從線上下載。