venv — 建立虛擬環境¶
在 3.3 版本加入。
原始碼: Lib/venv/
venv 模組支援建立輕量級的“虛擬環境”，每個虛擬環境都有自己獨立的 Python 包集，這些包安裝在它們的 site 目錄中。虛擬環境是基於現有的 Python 安裝建立的，這個安裝被稱為虛擬環境的“基礎” Python。預設情況下，它與基礎環境中的包是隔離的，因此只有明確安裝在虛擬環境中的包才可用。有關更多資訊，請參閱 虛擬環境 和 site 的 虛擬環境文件。
當從虛擬環境內部使用時，像 pip 這樣的常用安裝工具將把 Python 包安裝到虛擬環境中，而無需顯式告知。
虛擬環境（除其他外）是：
用於包含特定 Python 直譯器以及支援專案（庫或應用程式）所需的軟體庫和二進位制檔案。預設情況下，它們與來自其他虛擬環境的軟體以及安裝在作業系統上的 Python 直譯器和庫是隔離的。
包含在一個目錄中，通常在專案目錄中命名為
.venv或venv，或者在一個用於存放大量虛擬環境的容器目錄中，例如~/.virtualenvs。不納入 Git 等原始碼控制系統。
被視為一次性的——刪除並從頭開始重新建立它應該是簡單的。您不應將任何專案程式碼放入環境中。
不被視為可移動或可複製——您只需在目標位置重新建立相同的環境。
有關 Python 虛擬環境的更多背景資訊，請參閱 PEP 405。
可用性: 非 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 上是 Lib\site-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.
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
有關更多資訊，請參閱 關於執行策略。
建立的 pyvenv.cfg 檔案還包含 include-system-site-packages 鍵，如果 venv 使用 --system-site-packages 選項執行，則設定為 true，否則設定為 false。
除非提供了 --without-pip 選項，否則將呼叫 ensurepip 來引導 pip 到虛擬環境中。
可以向 venv 提供多個路徑，在這種情況下，將根據給定的選項在每個提供的路徑上建立一個相同的虛擬環境。
Venvs 的工作原理¶
當 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 |
|
fish |
|
|
csh/tcsh |
|
|
pwsh |
|
|
Windows |
cmd.exe |
|
PowerShell |
|
已在 3.4 版本中新增： fish 和 csh 啟用指令碼。
已在 3.8 版本中新增： PowerShell 啟用指令碼在 POSIX 下安裝，以支援 PowerShell Core。
您並不需要特別**啟用**虛擬環境，因為您可以在呼叫 Python 時直接指定該環境的 Python 直譯器的完整路徑。此外，環境中安裝的所有指令碼都應該能夠無需啟用即可執行。
為了實現這一點，安裝到虛擬環境中的指令碼會有一個指向環境 Python 直譯器的“shebang”行，格式為 #!/<path-to-venv>/bin/python。這意味著指令碼將使用該直譯器執行，而與 PATH 的值無關。在 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 已安裝在虛擬環境中。這使用
ensurepip和--default-pip選項。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 版本中更改： 使用 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()的一部分進行復制，而不是像 3.7.2 版本那樣在setup_scripts()中進行。使用符號連結時，將連結原始可執行檔案。
還有一個模組級別的便捷函式：
- 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物件，並呼叫其create()方法，傳入 env_dir 引數。在 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)
此指令碼也可 線上 下載。