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。