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