4. 在 Windows 上使用 Python

本文档旨在概述在 Microsoft Windows 上使用 Python 时应了解的 Windows 特定行为。

与大多数 Unix 系统和服务不同，Windows 不包含系统支持的 Python 安装。为了使 Python 可用，CPython 团队多年来一直在每个 版本 中编译 Windows 安装程序。这些安装程序主要用于添加 Python 的每个用户安装，核心解释器和库由单个用户使用。安装程序还可以为单个机器的所有用户安装，并且还提供单独的 ZIP 文件用于应用程序本地分发。

如 PEP 11 中所述，Python 版本仅在 Microsoft 认为该平台处于扩展支持阶段时才支持 Windows 平台。这意味着 Python 3.12 支持 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.12 安装程序供下载 - 两种用于解释器的 32 位版本，两种用于 64 位版本。网络安装程序是一个小型初始下载，它将根据需要自动下载所需的组件。脱机安装程序包含默认安装所需的组件，仅在需要可选功能时才需要互联网连接。有关在安装过程中避免下载的其他方法，请参阅 无需下载安装。

启动安装程序后，可以选择两个选项之一

如果您选择“立即安装”

• 您不需要成为管理员（除非需要系统更新 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 [directory]	预先下载所有组件
/log [filename]	指定日志文件位置

所有其他选项都以 name=value 的形式传递，其中 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	安装 Python Launcher for Windows.	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.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.2. Microsoft Store 包

在 3.7.2 版本中添加。

Microsoft Store 包是一个易于安装的 Python 解释器，主要用于交互式使用，例如，学生使用。

要安装该包，请确保您拥有最新的 Windows 10 更新，并在 Microsoft Store 应用中搜索“Python 3.12”。确保您选择的应用是由 Python 软件基金会发布的，并安装它。

警告

Python 将始终在 Microsoft Store 上免费提供。如果您被要求付费，则您没有选择正确的软件包。

安装后，可以通过在“开始”中找到 Python 来启动它。或者，它将通过在任何命令提示符或 PowerShell 会话中键入 python 来使用。此外，可以通过键入 pip 或 idle 来使用 pip 和 IDLE。IDLE 也可以在“开始”中找到。

所有三个命令也都可以使用版本号后缀，例如，作为 python3.exe 和 python3.x.exe 以及 python.exe（其中 3.x 是您要启动的特定版本，例如 3.12）。通过“开始”打开“管理应用执行别名”以选择与每个命令关联的 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 开发人员的摘要。

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 上的包信息页面是 www.nuget.org/packages/python（64 位版本）和 www.nuget.org/packages/pythonx86（32 位版本）。

4.4. 可嵌入包

在 3.5 版本中添加。

嵌入式发行版是一个 ZIP 文件，其中包含一个最小的 Python 环境。它旨在作为另一个应用程序的一部分，而不是直接被最终用户访问。

解压缩后，嵌入式发行版（几乎）完全与用户的系统隔离，包括环境变量、系统注册表设置和已安装的包。标准库被包含为预编译和优化的 .pyc 文件，这些文件位于一个 ZIP 文件中，并且提供了 python3.dll、python37.dll、python.exe 和 pythonw.exe。Tcl/tk（包括所有依赖项，如 Idle）、pip 和 Python 文档不包括在内。

注意

嵌入式发行版不包括 Microsoft C 运行时，应用程序安装程序有责任提供它。运行时可能已在用户的系统上安装，或者通过 Windows 更新自动安装，可以通过在系统目录中查找 ucrtbase.dll 来检测它。

第三方包应由应用程序安装程序与嵌入式发行版一起安装。使用 pip 管理依赖项（如常规 Python 安装）不受此发行版支持，尽管在某些情况下，可以包含和使用 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://docs.microsoft.com/en-us/windows/win32/procthread/environment-variables

Windows 上环境变量概述

https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1

set 命令，用于临时修改环境变量

https://docs.microsoft.com/en-us/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（Windows Subsystem for Linux））中被广泛使用。

您可以使用 Python UTF-8 模式 将默认文本编码更改为 UTF-8。您可以通过 -X utf8 命令行选项或 PYTHONUTF8=1 环境变量来启用 Python UTF-8 模式。请参见 PYTHONUTF8 以了解如何启用 UTF-8 模式，以及 旁注：设置环境变量 以了解如何修改环境变量。

启用 Python UTF-8 模式 后，您仍然可以使用系统编码（ANSI 代码页）通过“mbcs”编解码器。

请注意，将 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.12），您会注意到 Python 3.12 已启动 - 要启动 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: 参数时，指定公司将选择范围限制为来自该提供商的运行时，而仅指定标签将从所有提供商中选择。请注意，省略斜杠意味着标签

# 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 参数，并使用完整的标签。

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 文件 - 当前用户的应用程序数据目录中的 py.ini (%LOCALAPPDATA% 或 $env:LocalAppData) 以及与启动器相同的目录中的 py.ini。相同的 .ini 文件用于启动器的“控制台”版本（即 py.exe）和“windows”版本（即 pyw.exe）。

在“应用程序目录”中指定的自定义将优先于可执行文件旁边的自定义，因此用户（可能没有对启动器旁边的 .ini 文件的写入权限）可以覆盖该全局 .ini 文件中的命令。

4.8.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 版本，并使用为该主版本找到的最新次版本，这很可能是，但不能保证，是该系列中最近安装的版本。

在安装了相同（主版本.次版本）Python 版本的 32 位和 64 位实现的 64 位 Windows 上，始终优先使用 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.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 主目录”。否则，将使用主 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 文件，其中包含要包含的目录。这将忽略注册表和环境变量中列出的路径，还会忽略 site，除非列出了 import site。

• 如果您在自己的可执行文件中加载 python3.dll 或 python37.dll，请在 Py_Initialize() 之前显式调用 Py_SetPath() 或（至少）Py_SetProgramName()。

• 清除和/或覆盖 PYTHONPATH 并在从您的应用程序启动 python.exe 之前设置 PYTHONHOME。

• 如果您无法使用之前的建议（例如，您是一个允许人们直接运行 python.exe 的发行版），请确保您的安装目录中存在地标文件（Lib\os.py）。（请注意，它不会在 ZIP 文件中被检测到，但会检测到正确命名的 ZIP 文件。）

这些将确保系统范围安装中的文件不会优先于与您的应用程序捆绑在一起的标准库副本。否则，您的用户可能会在使用您的应用程序时遇到问题。请注意，第一个建议是最好的，因为其他建议可能仍然容易受到注册表和用户 site-packages 中的非标准路径的影响。

在版本 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.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 解释器。

有关具有预编译安装程序的平台的详细信息，请参阅 适用于 Windows 的 Python。