建立虛擬環境¶

虛擬環境是透過執行venv 模組來建立：

python-mvenv/path/to/new/virtual/environment

執行此命令會建立目標目錄（同時也會建立任何還不存在的父目錄）並在目錄中放置一個名為pyvenv.cfg 的檔案，其中包含一個指向執行該命令的 Python 安裝路徑的home 鍵。它同時會建立一個bin （在 Windows 上為Scripts）子目錄，其中包含一個 Python 二進位檔案的副本/符號連結（根據建立環境時使用的平台或引數而定）。此外，它還會建立一個lib/pythonX.Y/site-packages 子目錄（在 Windows 上為Lib\site-packages）。如果指定的目錄已存在，則將重新使用該目錄。

在 Windows 上，執行以下命令以使用venv：

PS>python-mvenvC:\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. bysourcing 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).

PSC:\>Set-ExecutionPolicy-ExecutionPolicyRemoteSigned-ScopeCurrentUser

被建立的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> 需要替換成包含虛擬環境的目錄路徑）

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

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

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

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

API¶

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

classvenv.EnvBuilder(system_site_packages=False,clear=False,symlinks=False,upgrade=False,with_pip=False,prompt=None,upgrade_deps=False,*,scm_ignore_files=frozenset())¶

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

• 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 （子類別）:

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

每個 methodsensure_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：

importosimportos.pathfromsubprocessimportPopen,PIPEimportsysfromthreadingimportThreadfromurllib.parseimporturlparsefromurllib.requestimporturlretrieveimportvenvclassExtendedEnvBuilder(venv.EnvBuilder):"""    此建構子會安裝 setuptools 和 pip，使你能夠使用 pip 或    easy_install 安裝其他套件到建立的虛擬環境中。    :param nodist: 若為 true，則不會安裝 setuptools 和 pip 至                   所建立的虛擬環境中。    :param nopip: 若為 true，則不會安裝 pip 至所建立的                  虛擬環境中。    :param progress: 若安裝了 setuptools 或 pip，可透過傳入 progress                     可呼叫物件來監控安裝進度。若有指定，該可呼叫物件會接收兩個引數：                     一個表示進度的字串，以及一個表示該字串來源的情境。                     context 引數可能有三種值：                     'main' 表示該呼叫來自 virtualize() 本身，                     'stdout' 與 'stderr' 則分別表示從子行程輸出資料串流中                     讀取的輸出內容，該子行程用於安裝應用程式。                     若未指定可呼叫物件，則預設的進度資訊會輸出至 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)defpost_setup(self,context):"""        設定在建立虛擬環境時需預先安裝的套件。        :param context: 處理中的虛擬環境建立請求所需的資訊。        """os.environ['VIRTUAL_ENV']=context.env_dirifnotself.nodist:self.install_setuptools(context)# 沒有 setuptools 就無法安裝 pipifnotself.nopipandnotself.nodist:self.install_pip(context)defreader(self,stream,context):"""        從子行程的輸出串流中讀取每一列，並將其傳遞給進度回呼函式（若有指定），或將進度資訊寫入 sys.stderr。        """progress=self.progresswhileTrue:s=stream.readline()ifnots:breakifprogressisnotNone:progress(s,context)else:ifnotself.verbose:sys.stderr.write('.')else:sys.stderr.write(s.decode('utf-8'))sys.stderr.flush()stream.close()definstall_script(self,context,name,url):_,_,path,_,_,_=urlparse(url)fn=os.path.split(path)[-1]binpath=context.bin_pathdistpath=os.path.join(binpath,fn)# 將腳本下載到虛擬環境的執行檔資料夾中urlretrieve(url,distpath)progress=self.progressifself.verbose:term='\n'else:term=''ifprogressisnotNone: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()ifprogressisnotNone:progress('done.','main')else:sys.stderr.write('done.\n')# 清理——不再需要os.unlink(distpath)definstall_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=lambdao:o.startswith('setuptools-')ando.endswith('.tar.gz')files=filter(pred,os.listdir(context.bin_path))forfinfiles:f=os.path.join(context.bin_path,f)os.unlink(f)definstall_pip(self,context):"""        在虛擬環境中安裝 pip。        :param context: 處理中的虛擬環境建立請求相關資訊。        """url='https://bootstrap.pypa.io/get-pip.py'self.install_script(context,'pip',url)defmain(args=None):importargparseparser=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.')ifos.name=='nt':use_symlinks=Falseelse:use_symlinks=Trueparser.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)ifoptions.upgradeandoptions.clear:raiseValueError('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)fordinoptions.dirs:builder.create(d)if__name__=='__main__':rc=1try:main()rc=0exceptExceptionase:print('Error:%s'%e,file=sys.stderr)sys.exit(rc)

此腳本也可從線上下載。