4. 在 Windows 上使用 Python

本文件旨在概述在 Microsoft Windows 上使用 Python 時應瞭解的 Windows 特定行為。

與大多數 Unix 系統和服務不同，Windows 不包含系統支援的 Python 安裝。相反，Python 可以從許多分發商處獲取，包括直接從 CPython 團隊獲取。每個 Python 發行版都有其自身的優缺點，但是，與您正在使用的其他工具保持一致通常是一個值得的優點。在開始此處描述的過程之前，我們建議您調查現有工具，看看它們是否可以直接提供 Python。

要從 CPython 團隊獲取 Python，請使用 Python 安裝管理器。這是一個獨立工具，可讓 Python 在您的 Windows 計算機上作為全域性命令使用，與系統整合，並支援隨時間推移的更新。您可以從 python.org/downloads 或透過 Microsoft Store 應用程式下載 Python 安裝管理器。

安裝 Python 安裝管理器後，可以從任何終端使用全域性 python 命令啟動您當前最新版本的 Python。此版本可能會隨著您新增或刪除不同版本而隨時間更改，py list 命令將顯示當前版本。

通常，我們建議您為每個專案建立一個 虛擬環境，並在終端中執行 <env>\Scripts\Activate 來使用它。這提供了專案之間的隔離、長期的一致性，並確保包新增的額外命令在您的會話中也可用。使用 python -m venv <env path> 建立虛擬環境。

如果 python 或 py 命令似乎不起作用，請參閱下面的 故障排除 部分。有時需要額外的手動步驟來配置您的電腦。

除了使用 Python 安裝管理器之外，還可以將 Python 作為 NuGet 包獲取。有關這些包的更多資訊，請參閱下面的 nuget.org 包。

可嵌入發行版是適合嵌入到大型應用程式中的最小 Python 包。它們可以使用 Python 安裝管理器安裝。有關這些包的更多資訊，請參閱下面的 可嵌入包。

4.1. Python 安裝管理器

4.1.1. 安裝

Python 安裝管理器可以從 Microsoft Store 應用安裝，也可以從 python.org/downloads 下載並安裝。這兩個版本是相同的。

透過 Store 安裝，只需點選“安裝”。完成後，開啟終端並鍵入 python 即可開始使用。

要安裝從 python.org 下載的檔案，可以雙擊並選擇“安裝”，或者在 Windows Powershell 中執行 Add-AppxPackage <path to MSIX>。

安裝後，python、py 和 pymanager 命令應該可用。如果您有現有的 Python 安裝，或者您修改了您的 PATH 變數，您可能需要刪除它們或撤消修改。有關修復不起作用的命令的更多幫助，請參閱 故障排除。

首次安裝執行時，您可能會被提示將目錄新增到 PATH。如果您更喜歡使用 py 命令，這是可選的，但為那些喜歡所有別名（例如 python3.14.exe）都可用的人提供。預設情況下，目錄將是 %LocalAppData%\Python\bin，但可以由管理員自定義。點選“開始”並搜尋“編輯您的帳戶的環境變數”以開啟系統設定頁面以新增路徑。

您安裝的每個 Python 執行時都將有其自己的指令碼目錄。如果您想使用它們，這些也需要新增到 PATH。

Python 安裝管理器將自動更新到新版本。這不影響任何 Python 執行時的安裝。解除安裝 Python 安裝管理器不會解除安裝任何 Python 執行時。

如果您的環境中無法安裝 MSIX，例如，您正在使用不支援它的自動化部署軟體，或者目標是 Windows Server 2019，請參閱下面的 高階安裝 以獲取更多資訊。

4.1.2. 基本使用

啟動 Python 的推薦命令是 python，它將啟動指令碼請求的版本、活動的虛擬環境或預設安裝版本，除非另行配置，否則它將是最新穩定版本。如果沒有明確請求版本且根本沒有安裝執行時，則當前最新版本將自動安裝。

對於所有涉及多個執行時版本的場景，推薦的命令是 py。這可以在任何地方替代 python 或舊的 py.exe 啟動器。預設情況下，py 與 python 的行為匹配，但還允許命令列選項選擇特定版本以及子命令來管理安裝。這些將在下面詳細介紹。

由於 py 命令可能已經被以前的版本佔用，因此還有一個明確的 pymanager 命令。打算使用 Python 安裝管理器的指令碼化安裝應考慮使用 pymanager，因為它遇到與現有安裝衝突的可能性較小。這兩個命令之間唯一的區別是當不帶任何引數執行時：py 將安裝並啟動您的預設直譯器，而 pymanager 將顯示幫助（pymanager exec ... 提供了與 py ... 等效的行為）。

這些命令中的每一個也都帶有一個避免建立控制檯視窗的視窗版本。它們是 pyw、pythonw 和 pymanagerw。還包含一個 python3 命令，它模仿 python 命令。它旨在捕獲在 Windows 上意外使用典型 POSIX 命令的情況，但不打算廣泛使用或推薦。

要啟動您的預設執行時，請執行 python 或 py，並傳入您希望傳遞給執行時的引數（例如指令碼檔案或要啟動的模組）

$> py
...
$> python my-script.py
...
$> py -m this
...

可以使用 PYTHON_MANAGER_DEFAULT 環境變數或配置檔案覆蓋預設執行時。有關配置設定的資訊，請參閱 配置。

要啟動特定執行時，py 命令接受 -V:<TAG> 選項。此選項必須在所有其他選項之前指定。標籤是執行時識別符號的一部分或全部；對於 CPython 團隊的執行時，它看起來像版本，可能帶有平臺。為了相容性，在標籤引用官方版本並以 3 開頭的情況下，可以省略 V:。

$> py -V:3.14 ...
$> py -V:3-arm64 ...

來自其他分發商的執行時可能還需要包含*公司*。這應該用斜槓與標籤分開，並且可以作為字首。當公司是 PythonCore 時，指定公司是可選的，當您想要特定公司的最新版本時，指定標籤是可選的（但不能省略斜槓）。

$> py -V:Distributor\1.0 ...
$> py -V:distrib/ ...

如果未指定版本，但傳遞了指令碼檔案，則將檢查指令碼的 *shebang 行*。這是一種特殊的檔案第一行格式，允許覆蓋命令。有關更多資訊，請參閱 Shebang 行。當沒有 shebang 行或無法解析時，指令碼將使用預設執行時啟動。

如果您在活動的虛擬環境中執行，沒有請求特定版本，並且沒有 shebang 行，則預設執行時將是該虛擬環境。在這種情況下，python 命令可能已經被覆蓋，並且這些檢查都沒有發生。但是，這種行為確保 py 命令可以互換使用。

當您啟動 python 或 py 但未安裝任何執行時，並且請求的版本是預設版本時，它將自動安裝然後啟動。否則，如果配置了自動安裝（最可能透過將 PYTHON_MANAGER_AUTOMATIC_INSTALL 設定為 true），或者使用了命令的 py exec 或 pymanager exec 形式，則將安裝請求的版本。

4.1.3. 命令幫助

py help 命令將顯示支援命令的完整列表及其選項。任何命令都可以傳入 -? 選項以顯示其幫助，或者將其名稱傳入 py help。

$> py help
$> py help install
$> py install /?

所有命令都支援一些通用選項，這些選項將由 py help 顯示。這些選項必須在任何子命令之後指定。指定 -v 或 --verbose 將增加顯示的輸出量，而 -vv 將進一步增加輸出量以用於除錯目的。傳遞 -q 或 --quiet 將減少輸出，而 -qq 將進一步減少輸出。

--config=<PATH> 選項允許指定一個配置檔案以一次性覆蓋多個設定。有關這些檔案的更多資訊，請參閱下面的 配置。

4.1.4. 列出執行時

$> py list [-f=|--format=<FMT>] [-1|--one] [--online|-s=|--source=<URL>] [<TAG>...]

可以使用 py list 檢視已安裝執行時的列表。可以新增一個或多個標籤形式的過濾器（帶或不帶公司指定符），每個標籤都可以包含 <、<=、>= 或 > 字首以限制範圍。

支援一系列格式，可以透過 --format=<FMT> 或 -f <FMT> 選項傳遞。格式包括 table（使用者友好的表格檢視）、csv（逗號分隔表格）、json（單個 JSON blob）、jsonl（每個結果一個 JSON blob）、exe（僅可執行檔案路徑）、prefix（僅字首路徑）。

--one 或 -1 選項僅顯示單個結果。如果包含預設執行時，則顯示預設執行時。否則，顯示“最佳”結果（“最佳”是故意模糊定義的，但通常是最新的版本）。py list --one <TAG> 顯示的結果將與 py -V:<TAG> 啟動的執行時匹配。

--only-managed 選項排除未由 Python 安裝管理器安裝的結果。這在確定哪些執行時可以透過 py 命令更新或解除安裝時很有用。

--online 選項是傳遞 --source=<URL> 和預設源的簡寫。傳遞其中任一選項將搜尋線上索引以查詢可以安裝的執行時。py list --online --one <TAG> 顯示的結果將與 py install <TAG> 安裝的執行時匹配。

$> py list --online 3.14

為了與舊啟動器相容，保留了 --list、--list-paths、-0 和 -0p 命令（例如 py -0p）。它們不允許附加選項，並且將生成舊版格式的輸出。

4.1.5. 安裝執行時

$> py install [-s=|--source=<URL>] [-f|--force] [-u|--update] [--dry-run] [<TAG>...]

可以使用 py install 新增新的執行時版本。可以指定一個或多個標籤，特殊標籤 default 可用於選擇預設值。安裝不支援範圍。

--source=<URL> 選項允許覆蓋用於獲取執行時的線上索引。這可以與離線索引一起使用，如 離線安裝 中所示。

傳遞 --force 將忽略任何快取檔案並移除任何現有安裝，以指定的版本替換。

傳遞 --update 將在新版本更新時替換現有安裝。否則，它們將被保留。如果 --update 未提供任何標籤，則如果存在新版本，Python 安裝管理器管理的所有安裝都將更新。更新將移除對安裝所做的任何修改，包括全域性安裝的包，但虛擬環境將繼續工作。

傳遞 --dry-run 將生成輸出和日誌，但不會修改任何安裝。

除了上述選項外，--target 選項會將執行時解壓到指定目錄，而不是進行正常安裝。這對於將執行時嵌入到更大的應用程式中很有用。

$> py install ... [-t=|--target=<PATH>] <TAG>

4.1.6. 離線安裝

要執行 Python 的離線安裝，您需要首先在一臺有網路訪問許可權的機器上建立一個離線索引。

$> py install --download=<PATH> ... <TAG>...

--download=<PATH> 選項將下載列出的標籤的包，並建立一個包含它們和 index.json 檔案的目錄，適用於後續安裝。整個目錄可以移動到離線機器並用於安裝一個或多個捆綁的執行時

$> py install --source="<PATH>\index.json" <TAG>...

Python 安裝管理器可以透過下載其安裝程式並將其移動到另一臺機器，然後進行安裝。

或者，離線索引目錄中的 ZIP 檔案可以簡單地傳輸到另一臺機器並解壓。這將不會以任何方式註冊安裝，因此必須透過直接引用解壓目錄中的可執行檔案來啟動，但在無法或不方便安裝 Python 安裝管理器的情況下，這有時是首選方法。

透過這種方式，可以在沒有網際網路訪問的機器上安裝和管理 Python 執行時。

4.1.7. 解除安裝執行時

$> py uninstall [-y|--yes] <TAG>...

可以使用 py uninstall 命令移除執行時。必須指定一個或多個標籤。此處不支援範圍。

--yes 選項繞過解除安裝前的確認提示。

除了單獨傳遞標籤外，還可以指定 --purge 選項。這將移除 Python 安裝管理器管理的所有執行時，包括清理“開始”選單、登錄檔和任何下載快取。未由 Python 安裝管理器安裝的執行時將不受影響，手動建立的配置檔案也不會受到影響。

$> py uninstall [-y|--yes] --purge

Python 安裝管理器可以透過 Windows “已安裝應用”設定頁面解除安裝。這不會移除任何執行時，並且它們仍然可用，儘管全域性 python 和 py 命令將被移除。重新安裝 Python 安裝管理器將允許您再次管理這些執行時。要完全清理所有 Python 執行時，請在解除安裝 Python 安裝管理器之前執行 --purge。

4.1.8. 配置

Python 安裝管理器透過配置檔案的層次結構、環境變數、命令列選項和登錄檔設定進行配置。通常，配置檔案能夠配置所有內容，包括其他配置檔案的位置，而登錄檔設定僅供管理員使用，並將覆蓋配置檔案。命令列選項會覆蓋所有其他設定，但並非所有選項都可用。

本節將描述預設值，但請注意，修改或覆蓋的安裝可能會以不同的方式解析設定。

全域性配置檔案可以由管理員配置，並將首先讀取。使用者配置檔案儲存在 %AppData%\Python\pymanager.json（預設情況下）中，並接下來讀取，覆蓋早期檔案中的任何設定。可以透過 PYTHON_MANAGER_CONFIG 環境變數或 --config 命令列選項指定附加配置檔案（但不能同時指定兩者）。

以下設定是在正常使用中可能被修改的。後面的章節列出了用於管理自定義的設定。

標準配置選項

配置鍵	環境變數	描述
default_tag	PYTHON_MANAGER_DEFAULT	啟動或安裝的首選預設版本。預設情況下，這被解釋為 CPython 團隊的最新非預釋出版本。
default_platform	PYTHON_MANAGER_DEFAULT_PLATFORM	啟動或安裝的首選預設平臺。這被視為指定標籤的字尾，因此如果存在 3.14-64 的安裝（並且 default_platform 是 -64），則 py -V:3.14 將優先選擇它，如果不存在標記的安裝，則使用 3.14。
logs_dir	PYTHON_MANAGER_LOGS	日誌檔案的寫入位置。預設情況下是 %TEMP%。
automatic_install	PYTHON_MANAGER_AUTOMATIC_INSTALL	如果為 True，則在指定特定執行時啟動時允許自動安裝。預設情況下為 True。
include_unmanaged	PYTHON_MANAGER_INCLUDE_UNMANAGED	如果為 True，則允許列出和啟動未由 Python 安裝管理器安裝的執行時，否則排除它們。預設情況下為 True。
shebang_can_run_anything	PYTHON_MANAGER_SHEBANG_CAN_RUN_ANYTHING	如果為 True，則允許 .py 檔案中的 shebang 啟動除 Python 執行時之外的應用程式，否則阻止。預設情況下為 True。
log_level	PYMANAGER_VERBOSE, PYMANAGER_DEBUG	設定預設輸出級別（0-50）。預設情況下是 20。較低的值會產生更多的輸出。環境變數是布林值，可能會在啟動期間產生額外的輸出，但隨後會被其他配置抑制。
confirm	PYTHON_MANAGER_CONFIRM	如果為 True，則在執行某些操作（例如解除安裝）之前進行確認，否則跳過確認。預設情況下為 True。
install.source	PYTHON_MANAGER_SOURCE_URL	覆蓋用於獲取新安裝的索引源。
list.format	PYTHON_MANAGER_LIST_FORMAT	指定 py list 命令使用的預設格式。預設情況下是 table。

帶點的名稱應巢狀在 JSON 物件中，例如，list.format 應指定為 {"list": {"format": "table"}}。

4.1.9. Shebang 行

如果指令碼檔案的第一行以 #! 開頭，則稱為“shebang”行。Linux 和其他類 Unix 作業系統原生支援此類行，它們在此類系統上通常用於指示指令碼應如何執行。python 和 py 命令允許在 Windows 上對 Python 指令碼使用相同的設施。

為了使 Python 指令碼中的 shebang 行在 Unix 和 Windows 之間可移植，支援許多“虛擬”命令來指定要使用的直譯器。支援的虛擬命令是

• /usr/bin/env <ALIAS>

• /usr/bin/env -S <ALIAS>

• /usr/bin/<ALIAS>

• /usr/local/bin/<ALIAS>

• <ALIAS>

例如，如果指令碼的第一行以

#! /usr/bin/python

將找到並使用預設 Python 或活動的虛擬環境。由於許多為在 Unix 上工作而編寫的 Python 指令碼已經包含此行，您應該會發現這些指令碼可以由啟動器使用而無需修改。如果您正在 Windows 上編寫一個希望在 Unix 上也有用的新指令碼，則應使用以 /usr 開頭的 shebang 行之一。

上述任何虛擬命令都可以將 <ALIAS> 替換為已安裝執行時的別名。也就是說，全域性別名目錄中生成的任何命令（您可能已將其新增到 PATH 環境變數中）都可以在 shebang 中使用，即使它不在您的 PATH 中。這允許使用諸如 /usr/bin/python3.12 之類的 shebang 來選擇特定的執行時。

如果沒有安裝執行時，或者啟用了自動安裝，則如果需要，將安裝請求的執行時。有關配置設定的資訊，請參閱 配置。

/usr/bin/env 形式的 shebang 行還將搜尋 PATH 環境變數中未識別的命令。這與 Unix env 程式的行為一致，該程式執行相同的搜尋，但優先啟動已知的 Python 命令。搜尋任意可執行檔案時可能會顯示警告，並且此搜尋可以透過 shebang_can_run_anything 配置選項停用。

不匹配任何模式的 Shebang 行被視為 *Windows* 可執行路徑，這些路徑是絕對路徑或相對於包含指令碼檔案的目錄。這對於僅限 Windows 的指令碼（例如安裝程式生成的指令碼）很方便，因為其行為與 Unix 風格的 shell 不相容。這些路徑可以加引號，並且可以包含多個引數，之後將追加指令碼的路徑和任何附加引數。此功能可以透過 shebang_can_run_anything 配置選項停用。

備註

Python 安裝管理器中 shebang 的行為與之前的 py.exe 啟動器略有不同，舊的配置選項不再適用。如果您特別依賴舊的行為或配置，我們建議保留舊版啟動器。它可以 獨立下載 並自行安裝。舊版啟動器的 py 命令將覆蓋 PyManager 的命令，您將需要使用 pymanager 命令進行安裝和解除安裝。

4.1.10. 高階安裝

對於無法安裝 MSIX 的情況，例如某些較舊的管理分發平臺，可以從 python.org 下載頁面獲取 MSI。此 MSI 沒有使用者介面，只能在其預設位置 Program Files 中執行每臺機器的安裝。它將嘗試修改系統 PATH 環境變數以包含此安裝位置，但請務必在您的配置上驗證此操作。

備註

Windows Server 2019 是 CPython 支援的唯一不支援 MSIX 的 Windows 版本。對於 Windows Server 2019，您應該使用 MSI。

請注意，MSI 軟體包不捆綁任何執行時，因此不適用於在離線環境中安裝，除非同時建立離線安裝索引。有關處理這些場景的資訊，請參閱 離線安裝 和 管理配置。

由 MSI 安裝的執行時與 MSIX 安裝的執行時共享，並且都僅限每個使用者。Python 安裝管理器不支援按機器安裝執行時。要模擬按機器安裝，您可以以管理員身份使用 py install --target=<shared location>，並新增您自己的系統範圍修改到 PATH、登錄檔或“開始”選單。

當安裝了 MSIX，但命令在 PATH 環境變數中不可用時，可以在 %LocalAppData%\Microsoft\WindowsApps\PythonSoftwareFoundation.PythonManager_3847v3x7pw1km 或 %LocalAppData%\Microsoft\WindowsApps\PythonSoftwareFoundation.PythonManager_qbz5n2kfra8p0 下找到它們，具體取決於它是從 python.org 還是透過 Windows 應用商店安裝的。不建議直接從 Program Files 執行可執行檔案。

要以程式設計方式安裝 Python 安裝管理器，最簡單的方法是使用 WinGet，它包含在所有受支援的 Windows 版本中

$> winget install 9NQ7512CXL7T -e --accept-package-agreements --disable-interactivity

# Optionally run the configuration checker and accept all changes
$> py install --configure -y

要下載 Python 安裝管理器並安裝到另一臺機器，以下 WinGet 命令將從商店下載所需檔案到您的“下載”目錄（新增 -d <location> 以自定義輸出位置）。這還會生成一個似乎不必要的 YAML 檔案，因為下載的 MSIX 可以透過啟動或使用以下命令安裝。

$> winget download 9NQ7512CXL7T -e --skip-license --accept-package-agreements --accept-source-agreements

要僅使用 PowerShell 以程式設計方式安裝或解除安裝 MSIX，建議使用 PowerShell cmdlet Add-AppxPackage 和 Remove-AppxPackage

$> Add-AppxPackage C:\Downloads\python-manager-25.0.msix
...
$> Get-AppxPackage PythonSoftwareFoundation.PythonManager | Remove-AppxPackage

可以透過將 AppInstaller 檔案傳遞給 Add-AppxPackage 命令來由 Windows 下載和安裝最新版本。這會使用 python.org 上的 MSIX 進行安裝，僅建議在無法透過應用商店（互動式或使用 WinGet）安裝的情況下使用。

$> Add-AppxPackage -AppInstallerFile https://www.python.org/ftp/python/pymanager/pymanager.appinstaller

其他工具和 API 也可用於為機器上的所有使用者預配 MSIX 包，但 Python 不認為這是一個受支援的場景。我們建議檢視 PowerShell Add-AppxProvisionedPackage cmdlet、原生 Windows PackageManager 類或您的部署工具的文件和支援。

無論安裝方法如何，使用者仍然需要安裝自己的 Python 副本，因為沒有辦法在沒有登入使用者的情況下觸發這些安裝。使用 MSIX 時，最新版本的 Python 將可供所有使用者安裝，無需網路訪問。

請注意，可從應用商店和 Python 網站下載的 MSIX 略有不同，不能同時安裝。在可能的情況下，我們建議使用上述 WinGet 命令從應用商店下載軟體包，以降低設定衝突安裝的風險。Python 安裝管理器沒有許可限制，不會阻止以這種方式使用應用商店軟體包。

4.1.11. 管理配置

有許多選項可能對管理員覆蓋 Python 安裝管理器的配置很有用。這些選項可用於提供本地快取、停用某些快捷方式型別、覆蓋捆綁內容。以上所有配置選項以及以下選項都可以設定。

可以透過在 HKEY_LOCAL_MACHINE\Software\Policies\Python\PyManager 下設定值來覆蓋登錄檔中的配置選項，其中值名稱與配置鍵匹配，值型別為 REG_SZ。請注意，此鍵本身可以自定義，但只能透過修改 Python 安裝管理器隨附的核心配置檔案。但是，我們建議僅使用登錄檔值將 base_config 設定為包含完整覆蓋集的 JSON 檔案。登錄檔鍵覆蓋將替換任何其他配置設定，而 base_config 允許使用者進一步修改他們可能需要的設定。

請注意，大多數具有環境變數的設定都支援這些變數，因為它們的預設設定指定了變數。如果您覆蓋它們，則環境變數將不再起作用，除非您用另一個環境變數覆蓋它。例如，confirm 的預設值實際上是 %PYTHON_MANAGER_CONFIRM%，它將在載入時解析變數。如果您將值覆蓋為 yes，則不再使用環境變數。如果您將值覆蓋為 %CONFIRM%，則將使用該環境變數。

作為路徑的配置設定被解釋為相對於指定它們的配置檔案所在的目錄。

管理配置選項

配置鍵	描述
base_config	要讀取的最高優先順序配置檔案。請注意，只有內建配置檔案和登錄檔可以修改此設定。
user_config	要讀取的第二個配置檔案。
additional_config	要讀取的第三個配置檔案。
registry_override_key	檢查覆蓋的登錄檔位置。請注意，只有內建配置檔案才能修改此設定。
bundled_dir	包含本地快取檔案的只讀目錄。
install.fallback_source	當主索引無法訪問時，要查詢的索引的路徑或 URL。
install.enable_shortcut_kinds	允許的快捷方式型別，以逗號分隔（例如 "pep514,start"）。已啟用的快捷方式仍可能被 disable_shortcut_kinds 停用。
install.disable_shortcut_kinds	要排除的快捷方式型別，以逗號分隔（例如 "pep514,start"）。已停用的快捷方式不會被 enable_shortcut_kinds 重新啟用。
pep514_root	用於讀取和寫入 PEP 514 條目的登錄檔位置。預設情況下是 HKEY_CURRENT_USER\Software\Python。
start_folder	用於寫入快捷方式的“開始”選單資料夾。預設情況下是 Python。此路徑是相對於使用者的“程式”資料夾的。
virtual_env	活動虛擬環境的路徑。預設情況下，這是 %VIRTUAL_ENV%，但可以設定為空以停用 venv 檢測。
shebang_can_run_anything_silently	如果為 True，則在 shebang 啟動非 Python 執行時應用程式時抑制可見警告。

4.1.12. 安裝自由執行緒二進位制檔案

在 3.13 版本加入。

自由執行緒構建的預構建發行版可以透過安裝帶有 t 字尾的標籤來獲得。

$> py install 3.14t
$> py install 3.14t-arm64
$> py install 3.14t-32

這將像往常一樣安裝和註冊。如果您沒有安裝其他執行時，則 python 將啟動此執行時。否則，您將需要使用 py -V:3.14t ...，或者，如果您已將全域性別名目錄新增到 PATH 環境變數中，則可以使用 python3.14t.exe 命令。

4.1.13. 故障排除

如果您的 Python 安裝管理器似乎無法正常工作，請仔細檢查這些測試和修復以檢視是否有幫助。如果仍然無法解決，請在 我們的 bug 跟蹤器 上報告問題，並附上任何相關的日誌檔案（預設寫入您的 %TEMP% 目錄）。

故障排除

症狀	嘗試的解決方法
當我在終端中輸入 python 時，它顯示“command not found”錯誤或開啟應用商店應用。	您是否安裝了 Python 安裝管理器？
	點選“開始”，開啟“管理應用執行別名”，並檢查“Python（預設）”的別名是否已啟用。如果已啟用，請嘗試停用然後重新啟用以重新整理命令。“Python（預設視窗化）”和“Python 安裝管理器”命令可能也需要重新整理。
	檢查 py 和 pymanager 命令是否工作。
當我在終端中輸入 py 時，它顯示“command not found”錯誤。	您是否安裝了 Python 安裝管理器？
	點選“開始”，開啟“管理應用執行別名”，並檢查“Python（預設）”的別名是否已啟用。如果已啟用，請嘗試停用然後重新啟用以重新整理命令。“Python（預設視窗化）”和“Python 安裝管理器”命令可能也需要重新整理。
當我在終端中輸入命令時，py 顯示“can’t open file”錯誤。	這通常意味著您安裝了舊版啟動器，並且它優先於 Python 安裝管理器。要刪除，請點選“開始”，開啟“已安裝應用”，搜尋“Python 啟動器”並解除安裝它。
python 未啟動與 py 相同的執行時	點選“開始”，開啟“已安裝應用”，查詢任何現有 Python 執行時，然後將其刪除或修改並停用 PATH 選項。
	點選“開始”，開啟“管理應用執行別名”，並檢查您的 python.exe 別名是否設定為“Python (default)”
python 和 py 未啟動我期望的執行時	檢查您的 PYTHON_MANAGER_DEFAULT 環境變數或 default_tag 配置。py list 命令將根據這些設定顯示您的預設值。
	由 Python 安裝管理器管理的安裝將優先於未管理的安裝。使用 py install 安裝您期望的執行時，或者配置您的預設標籤。
	未由 Python 安裝管理器管理的預釋出和實驗性安裝可能會優先於穩定版本。配置您的預設標籤或解除安裝預釋出執行時並使用 py install 重新安裝。
pythonw 或 pyw 未啟動與 python 或 py 相同的執行時	點選“開始”，開啟“管理應用執行別名”，並檢查您的 pythonw.exe 和 pyw.exe 別名是否與您的其他別名一致。
當我在終端中輸入 pip 時，它顯示“command not found”錯誤。	您是否激活了虛擬環境？在您的終端中執行 .venv\Scripts\activate 指令碼以啟用。
	軟體包可能可用，但缺少生成的可執行檔案。我們建議改用 python -m pip 命令，或者，python -m pip install --force pip 命令將重新建立可執行檔案並向您顯示要新增到 PATH 的路徑。這些指令碼是為每個執行時單獨分離的，因此您可能需要新增多個路徑。

4.2. 可嵌入包

在 3.5 版本加入。

嵌入式分發是一個 ZIP 檔案，包含一個最小的 Python 環境。它旨在作為另一個應用程式的一部分執行，而不是由終端使用者直接訪問。

要安裝嵌入式分發版，我們建議使用帶有 --target 選項的 py install

$> py install 3.14-embed --target=runtime

解壓後，嵌入式發行版（幾乎）與使用者系統完全隔離，包括環境變數、系統登錄檔設定和已安裝的包。標準庫以預編譯和最佳化的 .pyc 檔案形式包含在 ZIP 中，並提供 python3.dll、python313.dll、python.exe 和 pythonw.exe。不包括 Tcl/tk（包括所有依賴項，如 Idle）、pip 和 Python 文件。

包含一個預設的 ._pth 檔案，它進一步限制了預設搜尋路徑（如下面的 查詢模組 中所述）。此檔案旨在供嵌入者根據需要修改。

第三方包應由應用程式安裝程式與嵌入式分發版一起安裝。此分發版不支援像常規 Python 安裝一樣使用 pip 管理依賴項，儘管經過一些小心，可能會包含並使用 pip 進行自動更新。通常，第三方包應被視為應用程式的一部分（“vendoring”），以便開發人員可以在向用戶提供更新之前確保與新版本的相容性。

下面描述了此分發版的兩種推薦用例。

4.2.1. Python 應用程式

用 Python 編寫的應用程式不一定需要使用者知道這個事實。在這種情況下，嵌入式分發版可以用於在安裝包中包含一個私有版本的 Python。根據它應該有多透明（或者相反，它應該看起來有多專業），有兩種選擇。

使用專用可執行檔案作為啟動器需要一些編碼，但為使用者提供了最透明的體驗。使用自定義啟動器，沒有明顯的跡象表明程式正在 Python 上執行：圖示可以自定義，公司和版本資訊可以指定，檔案關聯可以正常工作。在大多數情況下，自定義啟動器只需能夠使用硬編碼的命令列呼叫 Py_Main。

更簡單的方法是提供一個批處理檔案或生成的快捷方式，直接呼叫 python.exe 或 pythonw.exe 並帶有所需的命令列引數。在這種情況下，應用程式將顯示為 Python，而不是其實際名稱，使用者可能難以將其與其他正在執行的 Python 程序或檔案關聯區分開來。

對於後一種方法，包應作為目錄與 Python 可執行檔案一起安裝，以確保它們在路徑上可用。對於專用啟動器，包可以位於其他位置，因為有機會在啟動應用程式之前指定搜尋路徑。

4.2.2. 嵌入 Python

用原生程式碼編寫的應用程式通常需要某種形式的指令碼語言，嵌入式 Python 分發版可以用於此目的。通常，應用程式的大部分是原生程式碼，並且某些部分將呼叫 python.exe 或直接使用 python3.dll。對於這兩種情況，將嵌入式分發版解壓到應用程式安裝的子目錄中足以提供可載入的 Python 直譯器。

與應用程式使用一樣，包可以安裝到任何位置，因為在初始化直譯器之前有機會指定搜尋路徑。否則，使用嵌入式分發版與常規安裝之間沒有根本區別。

4.3. nuget.org 包

3.5.2 版本新增。

nuget.org 包是縮減大小的 Python 環境，旨在用於沒有系統範圍的 Python 安裝的持續整合和構建系統。雖然 nuget 是“.NET 的包管理器”，但它也完美適用於包含構建時工具的包。

請訪問 nuget.org 以獲取使用 nuget 的最新資訊。以下是足以滿足 Python 開發人員需求的摘要。

nuget.exe 命令列工具可以直接從 https://aka.ms/nugetclidl 下載，例如使用 curl 或 PowerShell。使用該工具，可以透過以下命令安裝 64 位或 32 位機器的最新 Python 版本

nuget.exe install python -ExcludeVersion -OutputDirectory .
nuget.exe install pythonx86 -ExcludeVersion -OutputDirectory .

要選擇特定版本，請新增 -Version 3.x.y。輸出目錄可以從 . 更改，包將安裝到子目錄中。預設情況下，子目錄的名稱與包相同，並且在不使用 -ExcludeVersion 選項的情況下，此名稱將包含安裝的特定版本。子目錄中有一個 tools 目錄，其中包含 Python 安裝。

# Without -ExcludeVersion
> .\python.3.5.2\tools\python.exe -V
Python 3.5.2

# With -ExcludeVersion
> .\python\tools\python.exe -V
Python 3.5.2

通常，nuget 包不可升級，新版本應並排安裝並使用完整路徑引用。或者，手動刪除包目錄並重新安裝。如果許多 CI 系統在構建之間不保留檔案，它們會自動執行此操作。

除了 tools 目錄之外，還有一個 build\native 目錄。這包含一個 MSBuild 屬性檔案 python.props，可以在 C++ 專案中使用它來引用 Python 安裝。包含這些設定將自動在您的構建中使用標頭檔案和匯入庫。

nuget.org 上的軟體包資訊頁面是 64 位版本 www.nuget.org/packages/python，32 位版本 www.nuget.org/packages/pythonx86，以及 ARM64 版本 www.nuget.org/packages/pythonarm64

4.3.1. 自由執行緒包

在 3.13 版本加入。

包含自由執行緒二進位制檔案的包名為 64 位版本的 python-freethreaded，32 位版本的 pythonx86-freethreaded，以及 ARM64 版本的 pythonarm64-freethreaded。這些包都包含 python3.13t.exe 和 python.exe 入口點，這兩個入口點都執行自由執行緒。

4.4. 其他捆綁包

除了標準 CPython 發行版，還有修改過的包，包括附加功能。以下是流行版本及其主要功能的列表

ActivePython

具有多平臺相容性、文件、PyWin32 的安裝程式

Anaconda

流行的科學模組（例如 numpy、scipy 和 pandas）和 conda 包管理器。

Enthought 部署管理器

“下一代 Python 環境和包管理器”。

以前 Enthought 提供 Canopy，但它 於 2016 年達到生命週期終點。

WinPython

Windows 特定發行版，帶有預構建的科學包和用於構建包的工具。

請注意，這些包可能不包含最新版本的 Python 或其他庫，並且不由核心 Python 團隊維護或支援。

4.5. 支援的 Windows 版本

如 PEP 11 中所述，Python 版本僅在 Microsoft 認為平臺處於擴充套件支援期時才支援 Windows 平臺。這意味著 Python 3.14 支援 Windows 10 及更高版本。如果您需要 Windows 7 支援，請安裝 Python 3.8。如果您需要 Windows 8.1 支援，請安裝 Python 3.12。

4.6. 移除 MAX_PATH 限制

Windows 歷史上將路徑長度限制為 260 個字元。這意味著超過此長度的路徑將無法解析並導致錯誤。

在最新版本的 Windows 中，此限制可以擴充套件到超過 32,000 個字元。您的管理員需要啟用“啟用 Win32 長路徑”組策略，或將登錄檔項 HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem 中的 LongPathsEnabled 設定為 1。

這允許 open() 函式、os 模組和大多數其他路徑功能接受並返回長度超過 260 個字元的路徑。

更改上述選項並重啟後，無需進一步配置。

4.7. UTF-8 模式

在 3.7 版本加入。

Windows 仍然使用舊版編碼作為系統編碼（ANSI 內碼表）。Python 將其用於文字檔案的預設編碼（例如 locale.getencoding()）。

這可能會導致問題，因為 UTF-8 在網際網路上和大多數 Unix 系統（包括 WSL (Windows Subsystem for Linux)）上廣泛使用。

您可以使用 Python UTF-8 模式 將預設文字編碼更改為 UTF-8。您可以透過 -X utf8 命令列選項或 PYTHONUTF8=1 環境變數啟用 Python UTF-8 模式。有關啟用 UTF-8 模式的資訊，請參閱 PYTHONUTF8，有關如何修改環境變數的資訊，請參閱 Python 安裝管理器。

當 Python UTF-8 模式 啟用時，您仍然可以透過“mbcs”編碼使用系統編碼（ANSI 內碼表）。

請注意，將 PYTHONUTF8=1 新增到預設環境變數將影響系統上所有 Python 3.7+ 應用程式。如果您有任何依賴舊版系統編碼的 Python 3.7+ 應用程式，建議臨時設定環境變數或使用 -X utf8 命令列選項。

備註

即使停用 UTF-8 模式，Python 在 Windows 上預設仍使用 UTF-8 進行以下操作

• 控制檯 I/O，包括標準 I/O（詳見 PEP 528）。

• 檔案系統編碼（詳見 PEP 529）。

4.8. 查詢模組

這些說明補充了 sys.path 模組搜尋路徑的初始化 中對 Windows 詳細說明的描述。

當未找到 ._pth 檔案時，sys.path 在 Windows 上的填充方式如下

• 在開頭新增一個空條目，對應當前目錄。

• 如果環境變數 PYTHONPATH 存在，如 環境變數 中所述，其條目將接下來新增。請注意，在 Windows 上，此變數中的路徑必須用分號分隔，以區別於驅動器識別符號（C:\ 等）中使用的冒號。

• 附加的“應用程式路徑”可以在登錄檔中新增，作為 \SOFTWARE\Python\PythonCore{version}\PythonPath 的子鍵，位於 HKEY_CURRENT_USER 和 HKEY_LOCAL_MACHINE 根鍵下。預設值為以分號分隔的路徑字串的子鍵將導致每個路徑被新增到 sys.path。（請注意，所有已知的安裝程式僅使用 HKLM，因此 HKCU 通常是空的。）

• 如果環境變數 PYTHONHOME 已設定，則假定為“Python 主目錄”。否則，主 Python 可執行檔案的路徑用於查詢“里程碑檔案”（Lib\os.py 或 pythonXY.zip），以推斷“Python 主目錄”。如果找到 Python 主目錄，則新增到 sys.path 的相關子目錄（Lib、plat-win 等）將基於該資料夾。否則，核心 Python 路徑將從登錄檔中儲存的 PythonPath 構建。

• 如果無法找到 Python 主目錄，並且環境中未指定 PYTHONPATH，也未找到登錄檔條目，則使用包含相對條目的預設路徑（例如 .\Lib;.\plat-win 等）。

如果在主可執行檔案旁邊或在可執行檔案上一級目錄中找到 pyvenv.cfg 檔案，則適用以下變體

• 如果 home 是絕對路徑且未設定 PYTHONHOME，則在推斷主位置時，將使用此路徑而不是主可執行檔案的路徑。

所有這些的最終結果是

• 當執行 python.exe 或主 Python 目錄中的任何其他 .exe（無論是已安裝版本還是直接來自 PCbuild 目錄）時，將推斷核心路徑，並忽略登錄檔中的核心路徑。登錄檔中的其他“應用程式路徑”始終會被讀取。

• 當 Python 託管在另一個 .exe 中（不同目錄，透過 COM 嵌入等）時，“Python 主目錄”將不會被推斷，因此將使用登錄檔中的核心路徑。登錄檔中的其他“應用程式路徑”始終會被讀取。

• 如果 Python 找不到其主目錄且沒有登錄檔值（凍結的 .exe，某些非常奇怪的安裝設定），您將獲得一個包含一些預設但相對路徑的路徑。

對於希望將 Python 打包到其應用程式或分發版中的人，以下建議將防止與其他安裝發生衝突

• 在可執行檔案旁邊包含一個 ._pth 檔案，其中包含要包含的目錄。這將忽略登錄檔和環境變數中列出的路徑，並且除非列出 import site，否則還會忽略 site。

• 如果您在自己的可執行檔案中載入 python3.dll 或 python37.dll，請在 Py_InitializeFromConfig() 之前顯式設定 PyConfig.module_search_paths。

• 在從您的應用程式啟動 python.exe 之前，清除和/或覆蓋 PYTHONPATH 並設定 PYTHONHOME。

• 如果您不能使用前面的建議（例如，您是一個允許人們直接執行 python.exe 的分發版），請確保您的安裝目錄中存在里程碑檔案（Lib\os.py）。 （請注意，它在 ZIP 檔案中不會被檢測到，但會檢測到正確命名的 ZIP 檔案。）

這將確保系統範圍安裝中的檔案不會優先於您的應用程式捆綁的標準庫副本。否則，您的使用者在使用您的應用程式時可能會遇到問題。請注意，第一個建議是最好的，因為其他建議可能仍然容易受到登錄檔和使用者站點包中非標準路徑的影響。

3.6 版中已更改: 新增 ._pth 檔案支援並從 pyvenv.cfg 中刪除 applocal 選項。

3.6 版中已更改: 當 pythonXX.zip 直接位於可執行檔案旁邊時，將其新增為潛在的里程碑。

自 3.6 版以來已棄用: 登錄檔下 Modules（而非 PythonPath）中指定的模組可以透過 importlib.machinery.WindowsRegistryFinder 匯入。此查詢器在 3.6.0 及更早版本的 Windows 上啟用，但將來可能需要顯式新增到 sys.meta_path。

4.9. 附加模組

儘管 Python 旨在跨所有平臺可移植，但有些功能是 Windows 獨有的。標準庫和外部庫中都有一些模組以及程式碼片段，可用於使用這些功能。

Windows 特定的標準模組在 MS Windows 特有服務 中有文件說明。

4.9.1. PyWin32

Mark Hammond 的 PyWin32 模組是用於高階 Windows 特有支援的模組集合。這包括以下實用程式

• 元件物件模型 (COM)

• Win32 API 呼叫

• 登錄檔

• 事件日誌

• Microsoft Foundation Classes (MFC) 使用者介面

PythonWin 是 PyWin32 附帶的一個 MFC 示例應用程式。它是一個可嵌入的 IDE，內建偵錯程式。

參見

Win32 如何操作...？

作者：Tim Golden

Python 和 COM

作者：David 和 Paul Boddie

4.9.2. cx_Freeze

cx_Freeze 將 Python 指令碼封裝成可執行的 Windows 程式（*.exe 檔案）。完成此操作後，您可以分發您的應用程式，而無需使用者安裝 Python。

4.10. 在 Windows 上編譯 Python

如果您想自己編譯 CPython，首先應該獲取 原始碼。您可以下載最新版本的原始碼，或者直接獲取一份新鮮的 檢出。

原始碼樹包含用於 Microsoft Visual Studio 的構建解決方案和專案檔案，Microsoft Visual Studio 是用於構建官方 Python 版本的編譯器。這些檔案位於 PCbuild 目錄中。

有關構建過程的常規資訊，請檢視 PCbuild/readme.txt。

有關擴充套件模組，請參閱 在 Windows 上構建 C 和 C++ 擴充套件。

4.11. 完整安裝程式 (已棄用)

自 3.14 版以來已棄用: 此安裝程式自 3.14 版起已棄用，並且不會為 Python 3.16 或更高版本生成。有關現代安裝程式，請參閱 Python 安裝管理器。

4.11.1. 安裝步驟

有四個 Python 3.14 安裝程式可供下載——32 位和 64 位直譯器各兩個。 網路安裝程式 是一個小的初始下載，它將根據需要自動下載所需的元件。 離線安裝程式 包含預設安裝所需的元件，並且只對可選功能需要網際網路連線。有關避免在安裝期間下載的其他方法，請參閱 不下載的安裝方式。

啟動安裝程式後，可以選擇以下兩個選項之一

如果您選擇“立即安裝”

• 您將 不需要 管理員許可權（除非需要 C 執行時庫的系統更新或您為所有使用者安裝 Python 安裝管理器）

• Python 將安裝到您的使用者目錄中

• Python 安裝管理器 將根據第一頁底部的選項安裝

• 標準庫、測試套件、啟動器和 pip 將被安裝

• 如果選中，安裝目錄將被新增到您的 PATH

• 快捷方式僅對當前使用者可見

選擇“自定義安裝”將允許您選擇要安裝的功能、安裝位置以及其他選項或安裝後操作。要安裝除錯符號或二進位制檔案，您需要使用此選項。

要執行所有使用者的安裝，您應該選擇“自定義安裝”。在這種情況下

• 您可能需要提供管理員憑據或批准

• Python 將安裝到 Program Files 目錄中

• Python 安裝管理器 將安裝到 Windows 目錄中

• 在安裝期間可以選擇可選功能

• 標準庫可以預編譯為位元組碼

• 如果選中，安裝目錄將被新增到系統 PATH

• 快捷方式適用於所有使用者

4.11.2. 移除 MAX_PATH 限制

Windows 歷史上將路徑長度限制為 260 個字元。這意味著超過此長度的路徑將無法解析並導致錯誤。

在最新版本的 Windows 中，此限制可以擴充套件到大約 32,000 個字元。您的管理員需要啟用“啟用 Win32 長路徑”組策略，或將登錄檔項 HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem 中的 LongPathsEnabled 設定為 1。

這允許 open() 函式、os 模組和大多數其他路徑功能接受並返回長度超過 260 個字元的路徑。

更改上述選項後，無需進一步配置。

3.6 版中已更改: Python 中已啟用對長路徑的支援。

4.11.3. 無 UI 安裝

安裝程式 UI 中可用的所有選項也可以從命令列指定，允許指令碼安裝程式在無人互動的情況下在多臺機器上覆制安裝。這些選項也可以在不抑制 UI 的情況下設定，以更改一些預設值。

以下選項（透過執行安裝程式並帶上 /? 找到）可以傳遞給安裝程式

名稱	描述
/passive	顯示進度，無需使用者互動
/quiet	安裝/解除安裝，不顯示任何 UI
/simple	阻止使用者自定義
/uninstall	移除 Python（無需確認）
/layout [目錄]	預下載所有元件
/log [檔名]	指定日誌檔案位置

所有其他選項都作為 name=value 傳遞，其中值通常是 0 表示停用某個功能，1 表示啟用某個功能，或者是一個路徑。可用選項的完整列表如下所示。

名稱	描述	預設
InstallAllUsers	執行系統範圍安裝。	0
TargetDir	安裝目錄	根據 InstallAllUsers 選擇
DefaultAllUsersTargetDir	所有使用者安裝的預設安裝目錄	%ProgramFiles%\Python X.Y 或 %ProgramFiles(x86)%\Python X.Y
DefaultJustForMeTargetDir	僅限我的安裝的預設安裝目錄	%LocalAppData%\Programs\Python\PythonXY 或 %LocalAppData%\Programs\Python\PythonXY-32 或 %LocalAppData%\Programs\Python\PythonXY-64
DefaultCustomTargetDir	UI 中顯示的預設自定義安裝目錄	(空)
AssociateFiles	如果也安裝了啟動器，則建立檔案關聯。	1
CompileAll	將所有 .py 檔案編譯為 .pyc。	0
PrependPath	將安裝目錄和指令碼目錄新增到 PATH 的開頭，並將 .PY 新增到 PATHEXT	0
AppendPath	將安裝目錄和指令碼目錄新增到 PATH 的末尾，並將 .PY 新增到 PATHEXT	0
Shortcuts	為直譯器、文件和 IDLE 建立快捷方式（如果已安裝）。	1
Include_doc	安裝 Python 手冊	1
Include_debug	安裝除錯二進位制檔案	0
Include_dev	安裝開發者標頭檔案和庫。省略此選項可能導致安裝無法使用。	1
Include_exe	安裝 python.exe 和相關檔案。省略此選項可能導致安裝無法使用。	1
Include_launcher	安裝 Python 安裝管理器。	1
InstallLauncherAllUsers	為所有使用者安裝啟動器。還需要將 Include_launcher 設定為 1	1
Include_lib	安裝標準庫和擴充套件模組。省略此選項可能導致安裝無法使用。	1
Include_pip	安裝捆綁的 pip 和 setuptools	1
Include_symbols	安裝除錯符號 (*.pdb)	0
Include_tcltk	安裝 Tcl/Tk 支援和 IDLE	1
Include_test	安裝標準庫測試套件	1
Include_tools	安裝實用指令碼	1
LauncherOnly	僅安裝啟動器。這將覆蓋大多數其他選項。	0
SimpleInstall	停用大多數安裝 UI	0
SimpleInstallDescription	當使用簡化安裝 UI 時要顯示的自定義訊息。	(空)

例如，要靜默安裝預設的系統範圍 Python 安裝，您可以使用以下命令（從提升的命令提示符）

python-3.9.0.exe /quiet InstallAllUsers=1 PrependPath=1 Include_test=0

為了讓使用者輕鬆安裝個人 Python 副本而無需測試套件，您可以提供一個帶有以下命令的快捷方式。這將顯示一個簡化的初始頁面並禁止自定義

python-3.9.0.exe InstallAllUsers=0 Include_launcher=0 Include_test=0
    SimpleInstall=1 SimpleInstallDescription="Just for me, no test suite."

（請注意，省略啟動器也會省略檔案關聯，僅建議在有包含啟動器的系統級安裝時用於每個使用者安裝。）

上述選項也可以在與可執行檔案同名的 unattend.xml 檔案中提供。此檔案指定了選項和值的列表。當值作為屬性提供時，如果可能，它將被轉換為數字。作為元素文字提供的值始終保留為字串。此示例檔案設定的選項與上一個示例相同

<Options>
    <Option Name="InstallAllUsers" Value="no" />
    <Option Name="Include_launcher" Value="0" />
    <Option Name="Include_test" Value="no" />
    <Option Name="SimpleInstall" Value="yes" />
    <Option Name="SimpleInstallDescription">Just for me, no test suite</Option>
</Options>

4.11.4. 不下載的安裝方式

由於 Python 的某些功能未包含在初始安裝程式下載中，因此選擇這些功能可能需要網際網路連線。為了避免這種需求，所有可能的元件都可以按需下載以建立完整的 佈局，無論選擇的功能如何，都不再需要網際網路連線。請注意，此下載可能比所需的大，但如果將執行大量安裝，則擁有本地快取副本非常有用。

從命令提示符執行以下命令，以下載所有可能需要的檔案。請記住將 python-3.9.0.exe 替換為您的安裝程式的實際名稱，並在其自己的目錄中建立佈局，以避免同名檔案之間的衝突。

python-3.9.0.exe /layout [optional target directory]

您還可以指定 /quiet 選項以隱藏進度顯示。

4.11.5. 修改安裝

Python 安裝完成後，您可以透過 Windows 的“程式和功能”工具新增或刪除功能。選擇 Python 條目並選擇“解除安裝/更改”以在維護模式下開啟安裝程式。

“修改”允許您透過修改複選框來新增或刪除功能——未更改的複選框將不會安裝或刪除任何內容。某些選項在此模式下無法更改，例如安裝目錄；要修改這些選項，您需要完全刪除並重新安裝 Python。

“修復”將使用當前設定驗證所有應安裝的檔案，並替換任何已刪除或修改的檔案。

“解除安裝”將完全刪除 Python，除了 Python 安裝管理器，它在“程式和功能”中有自己的條目。

4.11.6. 安裝自由執行緒二進位制檔案

在 3.13 版本加入。

要安裝已啟用自由執行緒的預構建二進位制檔案（請參閱 PEP 703），您應該選擇“自定義安裝”。選項的第二頁包含“下載自由執行緒二進位制檔案”複選框。

選擇此選項將下載並安裝額外的二進位制檔案到與主 Python 安裝相同的位置。主可執行檔名為 python3.13t.exe，其他二進位制檔案要麼帶有 t 字尾，要麼帶有完整的 ABI 字尾。Python 原始檔和捆綁的第三方依賴項與主安裝共享。

自由執行緒版本註冊為帶有標籤 3.13t 的常規 Python 安裝（對於這些平臺，通常帶有 -32 或 -arm64 字尾）。這允許工具發現它，並且 Python 安裝管理器 支援 py.exe -3.13t。請注意，啟動器會將 py.exe -3（或 python3 shebang）解釋為“最新的 3.x 安裝”，這將優先選擇自由執行緒二進位制檔案而不是常規二進位制檔案，而 py.exe -3.13 則不會。如果您使用短選項樣式，您可能更傾向於此時不安自由執行緒二進位制檔案。

要在命令列中指定安裝選項，請使用 Include_freethreaded=1。有關預先下載額外二進位制檔案以進行離線安裝的說明，請參閱 不下載的安裝方式。包含除錯符號和二進位制檔案的選項也適用於自由執行緒構建。

自由執行緒二進位制檔案也可在 nuget.org 上獲取。

4.12. Windows 版 Python 啟動器（已棄用）

自 3.14 版以來已棄用: 啟動器和此文件已被上述 Python 安裝管理器取代。此內容暫時保留以供歷史參考。

在 3.3 版本加入。

Windows 版 Python 啟動器是一個實用程式，有助於定位和執行不同的 Python 版本。它允許指令碼（或命令列）指示對特定 Python 版本的偏好，並將定位並執行該版本。

與 PATH 變數不同，啟動器將正確選擇最合適的 Python 版本。它將優先選擇每使用者安裝而非系統範圍安裝，並按語言版本排序，而不是使用最近安裝的版本。

啟動器最初在 PEP 397 中指定。

4.12.1. 入門

4.12.1.1. 從命令列

3.6 版中已更改。

系統範圍安裝的 Python 3.3 及更高版本將把啟動器放在您的 PATH 中。啟動器與所有可用版本的 Python 相容，因此安裝哪個版本無關緊要。要檢查啟動器是否可用，請在命令提示符中執行以下命令

py

您應該會發現您安裝的最新版本 Python 已啟動 - 它可以正常退出，並且所有附加的命令列引數都將直接傳送給 Python。

如果您安裝了多個 Python 版本（例如，3.7 和 3.14），您會注意到 Python 3.14 已啟動——要啟動 Python 3.7，請嘗試以下命令

py -3.7

如果你想要安裝的最新版本 Python 2，請嘗試此命令

py -2

如果出現以下錯誤，則表示您沒有安裝啟動器

'py' is not recognized as an internal or external command,
operable program or batch file.

此命令

py --list

顯示當前安裝的 Python 版本。

-x.y 引數是 -V:Company/Tag 引數的縮寫形式，它允許選擇特定的 Python 執行時，包括那些可能來自 python.org 以外的執行時。任何透過遵循 PEP 514 註冊的執行時都將可被發現。--list 命令以 -V: 格式列出所有可用的執行時。

使用 -V: 引數時，指定 Company 將把選擇限制為該提供商的執行時，而只指定 Tag 將從所有提供商中選擇。請注意，省略斜槓表示一個標籤

# Select any '3.*' tagged runtime
py -V:3

# Select any 'PythonCore' released runtime
py -V:PythonCore/

# Select PythonCore's latest Python 3 runtime
py -V:PythonCore/3

引數的短格式（-3）始終只從核心 Python 發行版中選擇，而不選擇其他發行版。但是，長格式（-V:3）將從任何發行版中選擇。

公司名稱以完整字串匹配，不區分大小寫。標籤以完整字串或字首匹配，前提是下一個字元是點號或連字元。這允許 -V:3.1 匹配 3.1-32，但不匹配 3.10。標籤使用數字順序排序（3.10 比 3.1 新），但使用文字進行比較（-V:3.01 不匹配 3.1）。

4.12.1.2. 虛擬環境

在 3.5 版本加入。

如果啟動器在未明確指定 Python 版本的情況下執行，並且存在一個活動的虛擬環境（使用標準庫 venv 模組或外部 virtualenv 工具建立），啟動器將執行虛擬環境的直譯器而不是全域性直譯器。要執行全域性直譯器，請停用虛擬環境，或明確指定全域性 Python 版本。

4.12.1.3. 從指令碼

讓我們建立一個測試 Python 指令碼——建立一個名為 hello.py 的檔案，內容如下

#! python
import sys
sys.stdout.write("hello from Python %s\n" % (sys.version,))

在 hello.py 所在的目錄中，執行命令

py hello.py

您應該會注意到列印的是您安裝的最新 Python 2.x 版本的版本號。現在嘗試將第一行更改為

#! python3

重新執行該命令現在應該列印最新的 Python 3.x 資訊。與上面的命令列示例一樣，您可以指定更明確的版本限定符。假設您安裝了 Python 3.7，請嘗試將第一行更改為 #! python3.7，您應該會發現列印的是 3.7 版本的資訊。

請注意，與互動式使用不同，裸“python”將使用您安裝的最新 Python 2.x 版本。這是為了向後相容和與 Unix 相容，在 Unix 中，python 命令通常指的是 Python 2。

4.12.1.4. 從檔案關聯

安裝啟動器時，應已將其與 Python 檔案（即 .py、.pyw、.pyc 檔案）關聯。這意味著當您在 Windows 資源管理器中雙擊這些檔案時，將使用啟動器，因此您可以使用上述相同的功能讓指令碼指定應使用的版本。

這樣做的主要好處是，單個啟動器可以根據第一行的內容同時支援多個 Python 版本。

4.12.2. Shebang 行

如果指令碼檔案的第一行以 #! 開頭，則稱為“shebang”行。Linux 和其他類 Unix 作業系統對此類行具有本機支援，它們通常在此類系統上用於指示指令碼應如何執行。此啟動器允許在 Windows 上對 Python 指令碼使用相同的設施，上述示例演示了其用法。

為了使 Python 指令碼中的 shebang 行在 Unix 和 Windows 之間可移植，此啟動器支援許多“虛擬”命令來指定要使用的直譯器。支援的虛擬命令有

• /usr/bin/env

• /usr/bin/python

• /usr/local/bin/python

• python

例如，如果指令碼的第一行以

#! /usr/bin/python

將找到並使用預設 Python 或活動的虛擬環境。由於許多為在 Unix 上工作而編寫的 Python 指令碼已經包含此行，您應該會發現這些指令碼可以由啟動器使用而無需修改。如果您正在 Windows 上編寫一個希望在 Unix 上也有用的新指令碼，則應使用以 /usr 開頭的 shebang 行之一。

上述任何虛擬命令都可以加上顯式版本字尾（只包含主版本，或主版本和次版本）。此外，可以透過在次版本後新增“-32”來請求 32 位版本。例如，/usr/bin/python3.7-32 將請求使用 32 位 Python 3.7。如果虛擬環境處於活動狀態，版本將被忽略並使用該環境。

3.7 版新增: 從 python launcher 3.7 開始，可以透過“-64”字尾請求 64 位版本。此外，可以指定主版本和架構而無需次版本（即 /usr/bin/python3-64）。

3.11 版中已更改: “-64”字尾已棄用，現在表示“任何非 i386/32 位架構”。要請求特定環境，請使用帶有完整標籤的新 -V:TAG 引數。

3.13 版中已更改: 引用 python 的虛擬命令現在優先使用活動的虛擬環境，而不是搜尋 PATH。這處理了 shebang 指定 /usr/bin/env python3 但活動環境中不存在 python3.exe 的情況。

/usr/bin/env 形式的 shebang 行還有一個特殊的屬性。在查詢已安裝的 Python 直譯器之前，此形式將搜尋可執行檔案 PATH 中與作為第一個引數提供的名稱匹配的 Python 可執行檔案。這與 Unix env 程式的行為相對應，後者執行 PATH 搜尋。如果在 env 命令後的第一個引數之後找不到匹配的可執行檔案，但該引數以 python 開頭，它將按其他虛擬命令的描述進行處理。可以設定環境變數 PYLAUNCHER_NO_SEARCH_PATH（為任何值）以跳過此 PATH 搜尋。

不符合這些模式的 Shebang 行將在啟動器 .INI 檔案 的 [commands] 部分中查詢。這可以用於以對您的系統有意義的方式處理某些命令。命令的名稱必須是單個引數（shebang 可執行檔案中沒有空格），替換的值是可執行檔案的完整路徑（.INI 中指定的附加引數將作為檔名的一部分被引用）。

[commands]
/bin/xpython=C:\Program Files\XPython\python.exe

未在 .INI 檔案中找到的任何命令都將被視為 Windows 可執行檔案路徑，這些路徑可以是絕對路徑，也可以是相對於包含指令碼檔案的目錄的相對路徑。這是為僅限 Windows 的指令碼（例如安裝程式生成的指令碼）提供便利，因為此行為與 Unix 風格的 shell 不相容。這些路徑可以被引用，並且可以包含多個引數，之後將附加指令碼的路徑和任何附加引數。

4.12.3. Shebang 行中的引數

shebang 行還可以指定要傳遞給 Python 直譯器的附加選項。例如，如果您有一個 shebang 行

#! /usr/bin/python -v

那麼 Python 將以 -v 選項啟動

4.12.4. 自定義

4.12.4.1. 透過 INI 檔案自定義

啟動器將搜尋兩個 .ini 檔案——當前使用者應用程式資料目錄中的 py.ini（%LOCALAPPDATA% 或 $env:LocalAppData）以及與啟動器在同一目錄中的 py.ini。控制檯版啟動器（即 py.exe）和 Windows 版啟動器（即 pyw.exe）都使用相同的 .ini 檔案。

“應用程式目錄”中指定的自定義將優先於可執行檔案旁邊的自定義，因此使用者（可能沒有對啟動器旁邊 .ini 檔案的寫入許可權）可以覆蓋該全域性 .ini 檔案中的命令。

4.12.4.2. 自定義預設 Python 版本

在某些情況下，命令中可以包含版本限定符，以指示命令將使用的 Python 版本。版本限定符以主版本號開頭，可以選擇後跟一個句點（'.'）和一個次版本說明符。此外，可以透過新增“-32”或“-64”來指定是否請求 32 位或 64 位實現。

例如，shebang 行 #!python 沒有版本限定符，而 #!python3 有一個只指定主版本的版本限定符。

如果命令中沒有找到版本限定符，則可以設定環境變數 PY_PYTHON 來指定預設的版本限定符。如果未設定，則預設為“3”。該變數可以指定任何可以在命令列上傳遞的值，例如“3”、“3.7”、“3.7-32”或“3.7-64”。 （請注意，“-64”選項僅適用於 Python 3.7 或更高版本隨附的啟動器。）

如果未找到次版本限定符，則可以設定環境變數 PY_PYTHON{major}（其中 {major} 是如上確定的當前主版本限定符）以指定完整版本。如果未找到此類選項，啟動器將列舉已安裝的 Python 版本，並使用為主版本找到的最新次要版本，這很可能是（但不保證是）該系列中最新安裝的版本。

在 64 位 Windows 上，如果同時安裝了相同（主.次）Python 版本的 32 位和 64 位實現，則始終優先選擇 64 位版本。這對於 32 位和 64 位啟動器實現都適用——如果可用，32 位啟動器將優先執行指定版本的 64 位 Python 安裝。這樣做是為了在只知道 PC 上安裝了哪些版本的情況下，而無需考慮安裝順序（即，無需知道是先安裝了 32 位還是 64 位 Python 及相應的啟動器），也可以預測啟動器的行為。如上所述，可以在版本說明符上使用可選的“-32”或“-64”字尾來更改此行為。

示例：

• 如果未設定任何相關選項，則命令 python 和 python2 將使用安裝的最新 Python 2.x 版本，而命令 python3 將使用安裝的最新 Python 3.x 版本。

• 命令 python3.7 將完全不諮詢任何選項，因為版本已完全指定。

• 如果 PY_PYTHON=3，則命令 python 和 python3 都將使用最新安裝的 Python 3 版本。

• 如果 PY_PYTHON=3.7-32，則命令 python 將使用 3.7 的 32 位實現，而命令 python3 將使用最新安裝的 Python（PY_PYTHON 完全未考慮，因為已指定主版本）。

• 如果 PY_PYTHON=3 且 PY_PYTHON3=3.7，則命令 python 和 python3 都將專門使用 3.7

除了環境變數，相同的設定也可以在啟動器使用的 .INI 檔案中配置。.INI 檔案中的部分稱為 [defaults]，鍵名將與不帶前導 PY_ 字首的環境變數相同（請注意 .INI 檔案中的鍵名不區分大小寫）。環境變數的內容將覆蓋 .INI 檔案中指定的內容。

例如:

• 設定 PY_PYTHON=3.7 等同於 INI 檔案包含

[defaults]
python=3.7

• 設定 PY_PYTHON=3 和 PY_PYTHON3=3.7 等同於 INI 檔案包含

[defaults]
python=3
python3=3.7

4.12.5. 診斷

如果設定了環境變數 PYLAUNCHER_DEBUG（任何值），啟動器將向 stderr（即控制檯）列印診斷資訊。雖然這些資訊同時冗長 又 簡潔，但它應該能讓您看到找到了哪些 Python 版本，為什麼選擇了特定版本，以及用於執行目標 Python 的確切命令列。它主要用於測試和除錯。

4.12.6. 空執行

如果設定了環境變數 PYLAUNCHER_DRYRUN（任何值），啟動器將輸出它將執行的命令，但不會實際啟動 Python。這對於希望使用啟動器檢測然後直接啟動 Python 的工具可能很有用。請注意，寫入標準輸出的命令始終使用 UTF-8 編碼，並且可能無法在控制檯中正確渲染。

4.12.7. 按需安裝

如果設定了環境變數 PYLAUNCHER_ALLOW_INSTALL（為任何值），並且請求的 Python 版本未安裝但在 Microsoft Store 上可用，啟動器將嘗試安裝它。這可能需要使用者互動才能完成，您可能需要再次執行該命令。

額外的 PYLAUNCHER_ALWAYS_INSTALL 變數導致啟動器始終嘗試安裝 Python，即使它已被檢測到。這主要用於測試（並且應與 PYLAUNCHER_DRYRUN 一起使用）。

4.12.8. 返回碼

Python 啟動器可能會返回以下退出程式碼。遺憾的是，無法將它們與 Python 本身的退出程式碼區分開來。

程式碼名稱如原始碼中所用，僅供參考。除了閱讀此頁面，沒有其他方法可以訪問或解析它們。條目按名稱的字母順序排列。

名稱	值	描述
RC_BAD_VENV_CFG	107	找到 pyvenv.cfg 但它已損壞。
RC_CREATE_PROCESS	101	啟動 Python 失敗。
RC_INSTALLING	111	安裝已開始，但命令需要在完成後重新執行。
RC_INTERNAL_ERROR	109	意外錯誤。請報告錯誤。
RC_NO_COMMANDLINE	108	無法從作業系統獲取命令列。
RC_NO_PYTHON	103	無法找到請求的版本。
RC_NO_VENV_CFG	106	需要 pyvenv.cfg 但未找到。