4. 在 Windows 上使用 Python

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

與大多數 Unix 系統和服務不同，Windows 不包含系統支援的 Python 安裝。為了使 Python 可用，CPython 團隊多年來一直在為每個發行版編譯 Windows 安裝程式。這些安裝程式主要用於新增 Python 的按使用者安裝，核心直譯器和庫由單個使用者使用。安裝程式還能夠為單臺機器的所有使用者安裝，並且可以為應用程式本地分發提供單獨的 ZIP 檔案。

正如 PEP 11 中指定的，Python 發行版僅在 Microsoft 認為該平臺處於擴充套件支援期間才支援 Windows 平臺。這意味著 Python 3.13 支援 Windows 8.1 及更高版本。如果您需要 Windows 7 支援，請安裝 Python 3.8。

Windows 有許多不同的安裝程式可用，每個都有其優點和缺點。

完整安裝程式包含所有元件，是開發人員將 Python 用於任何型別專案的最佳選擇。

Microsoft Store 包是 Python 的簡單安裝，適用於執行指令碼和包，以及使用 IDLE 或其他開發環境。它需要 Windows 10 及更高版本，但可以安全地安裝而不會損壞其他程式。它還提供了許多用於啟動 Python 及其工具的便捷命令。

nuget.org 包是為持續整合系統設計的輕量級安裝。它可用於構建 Python 包或執行指令碼，但不可更新且沒有使用者介面工具。

可嵌入包是 Python 的最小包，適合嵌入到更大的應用程式中。

4.1. 完整安裝程式

4.1.1. 安裝步驟

有四個 Python 3.13 安裝程式可供下載 - 每個直譯器的 32 位和 64 位版本各有兩個。Web 安裝程式是一個小的初始下載，它會自動下載所需的元件。離線安裝程式包含預設安裝所需的元件，並且僅在可選功能時需要 Internet 連線。有關在安裝過程中避免下載的其他方法，請參閱無需下載的安裝。

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

如果選擇“立即安裝”

• 您不需要成為管理員（除非需要 C 執行時庫的系統更新或您為所有使用者安裝 Windows 版 Python 啟動器）

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

• 將根據第一頁底部的選項安裝 Windows 版 Python 啟動器

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

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

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

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

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

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

• Python 將安裝到 Program Files 目錄中

• Windows 版 Python 啟動器將安裝到 Windows 目錄中

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

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

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

• 快捷方式可供所有使用者使用

4.1.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.1.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	將安裝目錄和 Scripts 目錄新增到 PATH 並將 .PY 新增到 PATHEXT	0
AppendPath	將安裝目錄和 Scripts 目錄附加到 PATH 並將 .PY 新增到 PATHEXT	0
Shortcuts	如果已安裝，則為直譯器、文件和 IDLE 建立快捷方式。	1
Include_doc	安裝 Python 手冊	1
Include_debug	安裝除錯二進位制檔案	0
Include_dev	安裝開發人員標頭和庫。省略此項可能會導致無法使用的安裝。	1
Include_exe	安裝 python.exe 和相關檔案。省略此項可能會導致無法使用的安裝。	1
Include_launcher	安裝 Windows 版 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	停用大多數安裝使用者介面	0
SimpleInstallDescription	當使用簡化的安裝使用者介面時顯示的自定義訊息。	（空）

例如，要靜默安裝預設的系統範圍 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.1.4. 不下載安裝

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

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

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

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

4.1.5. 修改安裝

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

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

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

“解除安裝”將完全刪除 Python，但 Windows 版 Python 啟動器 除外，它在“程式和功能”中有自己的條目。

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

在 3.13 版本中新增：（實驗性）

注意

本節中描述的所有內容都被認為是實驗性的，並且預計在未來的版本中會發生變化。

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

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

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

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

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

4.2. Microsoft Store 包

在 3.7.2 版本中新增。

Microsoft Store 包是一個易於安裝的 Python 直譯器，主要用於互動式使用，例如，由學生使用。

要安裝該包，請確保您擁有最新的 Windows 10 更新，並在 Microsoft Store 應用中搜索“Python 3.13”。確保您選擇的應用由 Python 軟體基金會發布，然後安裝它。

警告

Python 在 Microsoft Store 上始終免費提供。如果要求您付費，則表示您未選擇正確的包。

安裝後，可以透過在“開始”選單中找到 Python 來啟動它。或者，可以透過鍵入 python 從任何命令提示符或 PowerShell 會話中使用它。此外，可以透過鍵入 pip 或 idle 來使用 pip 和 IDLE。IDLE 也可以在“開始”選單中找到。

所有這三個命令也都有版本號字尾，例如，python3.exe 和 python3.x.exe 以及 python.exe（其中 3.x 是您要啟動的特定版本，例如 3.13）。透過“開始”選單開啟“管理應用執行別名”以選擇與每個命令關聯的 Python 版本。建議確保 pip 和 idle 與所選的 python 版本保持一致。

可以使用 python -m venv 建立虛擬環境，並像往常一樣啟用和使用。

如果您安裝了其他版本的 Python 並將其新增到您的 PATH 變數中，它將作為 python.exe 而不是來自 Microsoft Store 的版本提供。要訪問新安裝，請使用 python3.exe 或 python3.x.exe。

py.exe 啟動器將檢測到此 Python 安裝，但會優先選擇傳統安裝程式中的安裝。

要刪除 Python，請開啟“設定”並使用“應用和功能”，或者在“開始”選單中找到 Python 並右鍵單擊以選擇“解除安裝”。解除安裝將刪除您直接安裝到此 Python 安裝中的所有包，但不會刪除任何虛擬環境

4.2.1. 已知問題

4.2.1.1. 本地資料、登錄檔和臨時路徑的重定向

由於 Microsoft Store 應用的限制，Python 指令碼可能沒有對共享位置（例如 TEMP 和登錄檔）的完全寫入許可權。相反，它將寫入私有副本。如果您的指令碼必須修改共享位置，則需要安裝完整安裝程式。

在執行時，Python 將使用眾所周知的 Windows 資料夾和登錄檔的私有副本。例如，如果環境變數 %APPDATA% 為 c:\Users\<user>\AppData\，那麼寫入 C:\Users\<user>\AppData\Local 時將寫入 C:\Users\<user>\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.8_qbz5n2kfra8p0\LocalCache\Local\。

讀取檔案時，Windows 將從私有資料夾返回檔案，如果該檔案不存在，則從真實的 Windows 目錄返回檔案。例如，讀取 C:\Windows\System32 將返回 C:\Windows\System32 的內容以及 C:\Program Files\WindowsApps\package_name\VFS\SystemX86 的內容。

您可以使用 os.path.realpath() 查詢任何現有檔案的真實路徑

>>> import os
>>> test_file = 'C:\\Users\\example\\AppData\\Local\\test.txt'
>>> os.path.realpath(test_file)
'C:\\Users\\example\\AppData\\Local\\Packages\\PythonSoftwareFoundation.Python.3.8_qbz5n2kfra8p0\\LocalCache\\Local\\test.txt'

當寫入 Windows 登錄檔時，存在以下行為：

• 允許從 HKLM\\Software 讀取，並將結果與包中的 registry.dat 檔案合併。

• 如果對應的鍵/值存在（即修改現有鍵），則不允許寫入 HKLM\\Software。

• 只要包中不存在相應的鍵/值，並且使用者具有正確的訪問許可權，就允許寫入 HKLM\\Software。

有關這些限制的技術基礎的更多詳細資訊，請參閱 Microsoft 關於打包的完全信任應用的文件，目前可在 docs.microsoft.com/en-us/windows/msix/desktop/desktop-to-uwp-behind-the-scenes 上獲得

4.3. nuget.org 包

在 3.5.2 版本中新增。

nuget.org 包是為在沒有 Python 系統範圍安裝的持續整合和構建系統上使用的精簡型 Python 環境。雖然 nuget 是“用於 .NET 的包管理器”，但它也可以完美地用於包含構建時工具的包。

請訪問 nuget.org 獲取關於使用 nuget 的最新資訊。以下是為 Python 開發人員提供的足夠用的摘要。

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

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

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

# 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 上的包資訊頁面是 www.nuget.org/packages/python （用於 64 位版本），www.nuget.org/packages/pythonx86（用於 32 位版本）和 www.nuget.org/packages/pythonarm64（用於 ARM64 版本）。

4.3.1. 自由執行緒包

在 3.13 版本中新增：（實驗性）

注意

本節中描述的所有內容都被認為是實驗性的，並且預計在未來的版本中會發生變化。

包含自由執行緒二進位制檔案的包被命名為 python-freethreaded（用於 64 位版本），pythonx86-freethreaded（用於 32 位版本）和 pythonarm64-freethreaded（用於 ARM64 版本）。 這些包同時包含 python3.13t.exe 和 python.exe 入口點，這兩個入口點都以自由執行緒方式執行。

4.4. 可嵌入包

在 3.5 版本中新增。

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

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

注意

嵌入式發行版不包含 Microsoft C 執行時，並且應用程式安裝程式有責任提供它。執行時可能已經先前或透過 Windows 更新自動安裝在使用者的系統上，並且可以透過在系統目錄中查詢 ucrtbase.dll 來檢測到。

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

下面描述了此發行版的兩個推薦用例。

4.4.1. Python 應用程式

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

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

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

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

4.4.2. 嵌入 Python

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

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

4.5. 備用捆綁包

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

ActivePython

帶有跨平臺相容性、文件、PyWin32 的安裝程式

Anaconda

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

Enthought 部署管理器

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

以前 Enthought 提供了 Canopy，但它在 2016 年達到生命週期結束。

WinPython

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

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

4.6. 配置 Python

要從命令提示符方便地執行 Python，您可能需要考慮更改 Windows 中的一些預設環境變數。雖然安裝程式提供了一個為您配置 PATH 和 PATHEXT 變數的選項，但這僅對單個系統範圍的安裝可靠。如果您經常使用多個版本的 Python，請考慮使用 Windows 的 Python 啟動器。

4.6.1. 題外話：設定環境變數

Windows 允許在使用者級別和系統級別永久配置環境變數，或在命令提示符中臨時配置。

要臨時設定環境變數，請開啟命令提示符並使用 set 命令

C:\>set PATH=C:\Program Files\Python 3.9;%PATH%
C:\>set PYTHONPATH=%PYTHONPATH%;C:\My_python_lib
C:\>python

這些更改將應用於該控制檯中執行的任何進一步命令，並且將由從控制檯啟動的任何應用程式繼承。

在百分號內包含變數名稱將展開為現有值，允許您在開始或結束時新增新值。透過將包含 python.exe 的目錄新增到開頭來修改 PATH 是一種常見的方法，以確保啟動正確版本的 Python。

要永久修改預設環境變數，請單擊“開始”並搜尋“編輯環境變數”，或開啟“系統屬性”，高階系統設定，然後單擊 環境變數 按鈕。在此對話方塊中，您可以新增或修改使用者變數和系統變數。要更改系統變數，您需要對計算機的非受限訪問許可權（即管理員許可權）。

注意

Windows 將在系統變數之後連線使用者變數，這在修改 PATH 時可能會導致意外結果。

所有版本的 Python 都使用 PYTHONPATH 變數，因此您不應永久配置它，除非列出的路徑僅包含與所有已安裝的 Python 版本相容的程式碼。

另請參閱

https://learn.microsoft.com/windows/win32/procthread/environment-variables

Windows 上環境變數的概述

https://learn.microsoft.com/windows-server/administration/windows-commands/set_1

用於臨時修改環境變數的 set 命令

https://learn.microsoft.com/windows-server/administration/windows-commands/setx

用於永久修改環境變數的 setx 命令

4.6.2. 查詢 Python 可執行檔案

在 3.5 版本中更改。

除了使用為 Python 直譯器自動建立的“開始”選單項之外，您可能還希望在命令提示符中啟動 Python。安裝程式有一個選項可以為您設定。

在安裝程式的第一頁，可以選擇一個名為“將 Python 新增到 PATH”的選項，以便安裝程式將安裝位置新增到 PATH 中。還會新增 Scripts\ 資料夾的位置。這使您可以鍵入 python 來執行直譯器，以及使用 pip 來使用軟體包安裝程式。因此，您還可以使用命令列選項執行指令碼，請參閱 命令列 文件。

如果您在安裝時沒有啟用此選項，您始終可以重新執行安裝程式，選擇“修改”，然後啟用它。或者，您可以使用 附註：設定環境變數 中的說明手動修改 PATH。您需要將 PATH 環境變數設定為包含 Python 安裝的目錄，並與其他條目用分號分隔。一個示例變數可能如下所示（假設前兩個條目已存在）：

C:\WINDOWS\system32;C:\WINDOWS;C:\Program Files\Python 3.9

4.7. UTF-8 模式

在 3.7 版本中新增。

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

這可能會導致問題，因為 UTF-8 廣泛用於網際網路和大多數 Unix 系統，包括 WSL（適用於 Linux 的 Windows 子系統）。

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

啟用 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. 適用於 Windows 的 Python 啟動器

在 3.3 版本中新增。

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

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

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

4.8.1. 入門

4.8.1.1. 從命令列

在 3.6 版本中更改。

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

py

您應該會發現您安裝的最新版本的 Python 已啟動 - 它可以像往常一樣退出，並且指定的任何其他命令列引數都將直接傳送到 Python。

如果您安裝了多個 Python 版本（例如，3.7 和 3.13），您會注意到啟動的是 Python 3.13 - 要啟動 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:公司/標籤 引數的簡寫形式，它允許選擇特定的 Python 執行時，包括那些可能來自 python.org 以外的地方的執行時。按照 PEP 514 註冊的任何執行時都將被發現。--list 命令使用 -V: 格式列出所有可用的執行時。

使用 -V: 引數時，指定公司會將選擇限制為該提供商的執行時，而僅指定標籤將從所有提供商中選擇。請注意，省略斜槓表示標籤：

# 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.8.1.2. 虛擬環境

在 3.5 版本中新增。

如果啟動器在沒有顯式 Python 版本規範的情況下執行，並且虛擬環境（使用標準庫 venv 模組或外部 virtualenv 工具建立）處於活動狀態，則啟動器將執行虛擬環境的直譯器，而不是全域性直譯器。要執行全域性直譯器，請停用虛擬環境，或顯式指定全域性 Python 版本。

4.8.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.8.1.4. 從檔案關聯

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

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

4.8.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 啟動器 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 不在活動環境中存在的情況。

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

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

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

任何在 .INI 檔案中找不到的命令都會被視為 Windows 可執行檔案路徑，這些路徑是絕對路徑或相對於包含指令碼檔案的目錄的路徑。這對於僅 Windows 的指令碼（例如安裝程式生成的指令碼）來說很方便，因為該行為與 Unix 風格的 shell 不相容。這些路徑可以用引號括起來，並且可以包含多個引數，之後將附加指令碼的路徑和任何其他引數。

4.8.3. Shebang 行中的引數

Shebang 行還可以指定要傳遞給 Python 直譯器的其他選項。例如，如果你的 shebang 行是

#! /usr/bin/python -v

那麼 Python 將使用 -v 選項啟動。

4.8.4. 自定義

4.8.4.1. 透過 INI 檔案自定義

啟動器會搜尋兩個 .ini 檔案 - 當前使用者的應用程式資料目錄 (%LOCALAPPDATA% 或 $env:LocalAppData) 中的 py.ini 和與啟動器位於同一目錄中的 py.ini。相同的 .ini 檔案用於啟動器的“控制檯”版本（即 py.exe）和“視窗”版本（即 pyw.exe）。

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

4.8.4.2. 自定義預設 Python 版本

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

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

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

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

在安裝了同一 (major.minor) Python 版本的 32 位和 64 位實現的 64 位 Windows 上，始終優先選擇 64 位版本。對於啟動器的 32 位和 64 位實現來說都是如此 - 如果可用，32 位啟動器將優先執行指定版本的 64 位 Python 安裝。這樣，只需知道 PC 上安裝了哪些版本，而無需考慮它們的安裝順序（即，無需知道最後安裝的是 Python 的 32 位還是 64 位版本以及相應的啟動器），即可預測啟動器的行為。如上所述，可以在版本說明符上使用可選的 “-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.8.5. 診斷

如果設定了環境變數 PYLAUNCHER_DEBUG （設定為任何值），啟動器會將診斷資訊列印到 stderr（即控制檯）。 雖然這些資訊設法同時做到冗長和簡潔，但它應該允許您檢視已定位的 Python 版本、選擇特定版本的原因以及用於執行目標 Python 的確切命令列。它主要用於測試和除錯。

4.8.6. 空執行

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

4.8.7. 按需安裝

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

額外的 PYLAUNCHER_ALWAYS_INSTALL 變數會導致啟動器始終嘗試安裝 Python，即使檢測到它也是如此。 這主要用於測試（應該與 PYLAUNCHER_DRYRUN 一起使用）。

4.8.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，但未找到。

4.9. 查詢模組

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

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

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

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

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

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

• 如果無法找到 Python Home，則未在環境中指定 PYTHONPATH，並且找不到任何登錄檔條目，則將使用帶有相對條目的預設路徑（例如，.\Lib;.\plat-win 等）。

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

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

所有這些的最終結果是

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

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

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

對於那些想要將 Python 捆綁到其應用程式或發行版中的人，以下建議將防止與其他安裝發生衝突

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

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

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

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

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

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

在版本 3.6 中更改：新增 pythonXX.zip 作為直接與可執行檔案相鄰的潛在地標。

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

4.10. 其他模組

儘管 Python 旨在在所有平臺之間實現可移植性，但仍有一些功能是 Windows 特有的。 存在一些模組（都在標準庫和外部）和程式碼片段，用於使用這些功能。

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

4.10.1. PyWin32

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

• 元件物件模型 (COM)

• Win32 API 呼叫

• 登錄檔

• 事件日誌

• Microsoft 基礎類庫 (MFC) 使用者介面

PythonWin 是一個隨 PyWin32 一起釋出的 MFC 示例應用程式。它是一個帶有內建偵錯程式的可嵌入 IDE。

另請參閱

Win32 我該如何做…？

作者：Tim Golden

Python 和 COM

作者：David 和 Paul Boddie

4.10.2. cx_Freeze

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

4.11. 在 Windows 上編譯 Python

如果您想自己編譯 CPython，您應該做的第一件事是獲取原始碼。您可以下載最新版本的原始碼，或者直接獲取一個最新的檢出版本。

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

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

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

4.12. 其他平臺

隨著 Python 的持續開發，一些早期支援的平臺由於缺少使用者或開發者而不再支援。有關所有不支援的平臺的詳細資訊，請檢視 PEP 11。

• Windows CE 自 Python 3 以來不再支援（如果它曾經被支援過的話）。

• Cygwin 安裝程式也提供安裝 Python 直譯器

有關帶有預編譯安裝程式的平臺的詳細資訊，請參閱 Python for Windows。