venv
--- 建立虛擬環境¶
在 3.3 版被加入.
原始碼:Lib/venv/
venv
模組支援建立輕量級的「虛擬環境」,每個虛擬環境都有獨立安裝在其site
目錄中的一組 Python 套件。虛擬環境是建立在既有的 Python 安裝上(稱為該虛擬環境的「基底」Python)之上,可選擇與基底環境中的套件隔離,使得僅能存取明確安裝在虛擬環境中的套件。
在使用虛擬環境中時,像pip 這樣的常用安裝工具會自動將 Python 套件安裝至虛擬環境中,而不需要額外指定。
虛擬環境是(主要的特性):
用來包含特定的 Python 直譯器、函式庫與二進位檔案,以支援某個專案(函式庫或應用程式)。預設情況下,這些內容會與其他虛擬環境中的軟體以及作業系統中安裝的 Python 直譯器與函式庫隔離。
被包含在一個目錄中,通常命名為專案目錄下的
.venv
或venv
,也可能是在用來管理多個虛擬環境的容器目錄中,例如~/.virtualenvs
。不應提交至 Git 等版本控制系統。
被視為可拋棄的資源——應能簡單地刪除並從頭重新建立。請勿將任何專案程式碼放置於虛擬環境中。
不應移動或複製——若需在其他位置使用,應重新建立相同的虛擬環境。
更多關於 Python 虛擬環境的背景資訊請見PEP 405。
適用: not Android, not iOS, not WASI.
此模組在行動平台或WebAssembly 平台上不支援。
建立虛擬環境¶
虛擬環境是透過執行venv
模組來建立:
python-mvenv/path/to/new/virtual/environment
執行此命令會建立目標目錄(同時也會建立任何還不存在的父目錄)並在目錄中放置一個名為pyvenv.cfg
的檔案,其中包含一個指向執行該命令的 Python 安裝路徑的home
鍵。它同時會建立一個bin
(在 Windows 上為Scripts
)子目錄,其中包含一個 Python 二進位檔案的副本/符號連結(根據建立環境時使用的平台或引數而定)。此外,它還會建立一個lib/pythonX.Y/site-packages
子目錄(在 Windows 上為Libsite-packages
)。如果指定的目錄已存在,則將重新使用該目錄。
在 3.5 版的變更:目前建議使用venv
來建立虛擬環境。
Deprecated since version 3.6, removed in version 3.8:pyvenv 是在 Python 3.3 和 3.4 中建立虛擬環境的推薦工具,但在 Python 3.5 中已被直接執行venv
所取代。
在 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.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. bysourcing 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 命令來執行此操作:
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>
需要替換成包含虛擬環境的目錄路徑)
平台 | Shell | 啟動虛擬環境的指令 |
---|---|---|
POSIX | bash/zsh |
|
fish |
| |
csh/tcsh |
| |
pwsh |
| |
Windows | cmd.exe |
|
PowerShell |
|
在 3.4 版被加入:fish 和csh 啟動腳本。
在 3.8 版被加入:PowerShell 的啟動腳本安裝在 POSIX 上支援 PowerShell Core。
你不用特別開啟虛擬環境,你可以在呼叫 Python 時指定該環境下 Python 直譯器的完整路徑。此外,所有安裝在環境裡的腳本都應該都可以在未啟用虛擬環境的情況下運行。
為了實現這一點,安裝在虛擬環境中的腳本會有一個 "shebang" 列,此列指向該環境的 Python 直譯器#!/<path-to-venv>/bin/python
。這代表無論PATH
的值為何,該腳本都會在直譯器上運行。在 Windows 上,如果你安裝了Python Launcher for Windows,則支援 "shebang" 列處理。因此,在 Windows 檔案總管(Windows Explorer)中雙擊已安裝的腳本,應該可以在沒有啟用環境或將其加入PATH
的情況下正確地運行。
當虛擬環境被啟用時,VIRTUAL_ENV
環境變數會被設置為該環境的路徑。由於不需要明確啟用虛擬環境才能使用它。因此,無法依賴VIRTUAL_ENV
來判斷是否正在使用虛擬環境。
警告
因為安裝在環境中的腳本不應該預期該環境已經被啟動,所以它們的 shebang 列會包含環境直譯器的絕對路徑。因此,在一般情況下,環境本質上是不可攜帶的。你應該使用一個簡單的方法來重新建立一個環境(例如:如果你有一個名為requirements.txt
的需求檔案,你可以使用環境的pipinstall-rrequirements.txt
來安裝環境所需的所有套件)。如果出於某種原因,你需要將環境移至新位置,你應該在所需位置重新建立它,並刪除舊位置的環境。如果你移動環境是因為移動了其父目錄,你應該在新位置重新建立環境。否則,安裝在該環境中的軟體可能無法正常運作。
你可以在 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())¶
進行實例化時,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 (子類別):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)
每個 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:
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)
此腳本也可從線上下載。