4. 在 Windows 上使用 Python

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

与大多数Unix系统和服务不同，Windows不包括系统支持的Python安装。相反，Python可以从许多发行商获得，包括直接从CPython团队获得。每个Python发行版都有自己的优点和缺点，但是，与您正在使用的其他工具保持一致通常是值得的优点。在使用这里描述的过程之前，我们建议调查您现有的工具，看看它们是否可以直接提供Python。

要从 CPython 团队获取 Python，请使用 Python 安装管理器。 这是一个独立的工具，它使 Python 可以作为 Windows 机器上的全局命令使用，与系统集成，并支持随时间更新。 您可以从 python.org/downloads 或通过 Microsoft Store app 下载 Python 安装管理器。

一旦安装了Python安装管理器，就可以在任何终端上使用全局命令 python 启动当前最新版本的 Python。 当您添加或删除不同的版本时，该版本可能会随着时间的推移而变化，py list 命令将显示当前的版本。

总的来说，我们推荐你为每个项目创建一个 虚拟环境 并在你的终端里运行 <env>\Scripts\Activate 来使用它。 这提供了项目之间的隔离，时间变化后的一致性，并确保由软件包添加的额外命令在你的会话中同样可用。 创建虚拟环境是使用 python -m venv <env path>。

如果 python 或 py 命令显示不可用，请查看下面的 故障排查 一节。 有时还需要额外的手动操作步骤来配置你的 PC。

除了使用 Python 安装管理器，Python 也可以作为 NuGet 软件包来获取。 请参阅下面的 nuget.org 安装包 了解有关这些软件包的更多信息。

可嵌入分发版是适用于嵌入到更大的应用程序中的最小化的 Python 软件包。 它们可以使用 Python 安装管理器来安装。 请参阅下面的 可嵌入的包 了解有关这些软件包的更多信息。

4.1. Python 安装管理器

4.1.1. 安装

Python 安装管理器可从 Microsoft Store app 安装或是从 python.org/downloads 下载并安装。 这两个版本的内容是一致的。

要通过 Store 安装，只需点击 "Install"。 在安装完成之后，可打开一个终端并键入 python 以开始使用。

要安装从 python.org 下载的文件，只需双击并选择 "Install"，或是在 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。 另外还包括一个相当于 python 命令的 python3 命令。 它的目的是在 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 行，则默认运行时将是该虚拟环境。 在这种情况下，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 块)、jsonl (每个结果一个 JSON 块)、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运行时可以在不访问internet的主机上安装和管理。

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安装管理器由配置文件、环境变量、命令行选项和注册表设置组成。通常，配置文件能够配置所有内容，包括其他配置文件的位置，而注册表设置仅由管理员设置，并且将覆盖配置文件。命令行选项覆盖所有其他设置，但不是每个选项都可用。

本节将描述默认设置，但请注意，修改或覆盖的安装可能以不同的方式解析设置。

首先读取由管理员配置的全局配置文件，随后读取保存在:file:%AppData%\Python\pymanager.json`（默认情况下）的用户配置文件，覆盖以前文件中的任何设置。额外的配置文件可以指定为``PYTHON_MANAGER_CONFIG``环境变量或`--config``命令行选项（但不能同时指定两者）。

以下设置是在正常使用中可能被修改的设置。后面的部分列出了用于管理定制的选项。

标准配置选项

配置键

环境变量

描述

default_tag
PYTHON_MANAGER_DEFAULT

首选启动或安装的默认版本。 在默认情况下，这会被解读为来自 CPython 团队的最新非预发布版本。

default_platform

PYTHON_MANAGER_DEFAULT_PLATFORM

启动或安装的首选默认平台。这被视为指定标签的后缀，因此``py -V:3.14``如果存在（并且``default_platform``为``-64``），则更倾向于安装``3.14-64``，但如果不存在添加后的标签的安装，则将使用``3.14``。

logs_dir

PYTHON_MANAGER_LOGS

写入日志文件的位置。默认为:file:%TEMP%。

automatic_install

PYTHON_MANAGER_AUTOMATIC_INSTALL

真值表示当指定了要启动的运行时的时候允许自动安装。 默认为真值。

include_unmanaged

PYTHON_MANAGER_INCLUDE_UNMANAGED

真值表示允许列出和启动不是由 Python 安装管理器安装的运行时，假值表示排除它们。 默认为真值。

shebang_can_run_anything

PYTHON_MANAGER_SHEBANG_CAN_RUN_ANYTHING

真值表示允许 .py 文件中的 shebang 启动 Python 运行时之外的应用程序，假值表示阻止它们。 默认为真值。

log_level

PYMANAGER_VERBOSE, PYMANAGER_DEBUG

设置输出的默认级别（范围0-50）。默认值为20。数值越低，输出内容越详细。这些环境变量为布尔类型，可能在启动时产生额外输出，但后续会被其他配置抑制。

confirm

PYTHON_MANAGER_CONFIRM

若为 True，则在执行某些操作（如卸载）前进行确认；若为 False，则跳过确认。默认值为 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=<共享位置> 命令，并自行对 PATH、注册表或开始菜单进行全系统范围的修改。

当 MSIX 已安装但命令在 PATH 环境变量中不可用时，可在以下位置找到它们： 从 python.org 安装：%LocalAppData%\Microsoft\WindowsApps\PythonSoftwareFoundation.PythonManager_3847v3x7pw1km ；从 Windows 应用商店安装：%LocalAppData%\Microsoft\WindowsApps\PythonSoftwareFoundation.PythonManager_qbz5n2kfra8p0 。不建议直接从 Program Files 目录运行可执行文件。

若要以编程方式安装 Python 安装管理器，最简单的方法是使用 WinGet，它包含在所有受支持的 Windows 版本中：

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

# 可选地运行配置检查器并接受所有更改
$> 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%，但可设置为空以禁用虚拟环境检测。

shebang_can_run_anything_silently

当 shebang 启动的应用程序不是 Python 运行时，若要隐藏可见警告，可将此值设为 True。

4.1.12. 安装自由线程二进制文件

Added in version 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 安装管理器运行不正常，请尝试以下测试和修复方法，看看是否能解决问题。如果问题仍未解决，请前往我们的 错误跟踪器 报告问题，并附上所有相关的日志文件（默认情况下，日志文件会写入您的 %TEMP% 目录）。

故障排除

症状

可以尝试的事情

当我在终端中输入 python 时，出现“命令未找到”错误，或者打开了应用商店。

您是否 已安装 Python 安装管理器？

点击开始菜单，打开"管理应用执行别名"，检查"Python (默认)"的别名是否已启用。如果已启用，可以尝试禁用后重新启用以刷新命令。"Python (默认窗口化)"和"Python 安装管理器"命令可能也需要刷新。

检查 py 和 pymanager 命令是否能正常使用。

当我在终端中输入 py 时，出现“命令未找到”错误。

您是否 已安装 Python 安装管理器？

点击开始菜单，打开"管理应用执行别名"，检查"Python (默认)"的别名是否已启用。如果已启用，可以尝试禁用后重新启用以刷新命令。"Python (默认窗口化)"和"Python 安装管理器"命令可能也需要刷新。

当我在终端中输入 py 命令时，出现“无法打开文件”错误。

这通常意味着您安装了旧版启动器，并且它的优先级高于 Python 安装管理器。要解决此问题，请点击开始菜单，打开"已安装的应用"，搜索"Python 启动器"并卸载它。

python 和 py 命令启动的不是同一个 Python 运行时。

点击开始菜单，打开"已安装的应用"，查找任何已存在的 Python 运行时，然后删除它们，或者选择"修改"并禁用 PATH 选项。

点击开始菜单，打开"管理应用执行别名"，并确保您的 python.exe 别名设置为"Python (默认)"。

python 和 py 命令没有启动我期望的 Python 运行时。

Check your PYTHON_MANAGER_DEFAULT environment variable or default_tag configuration. The py list command will show your default based on these settings.

由 Python 安装管理器管理的安装会优先于未管理的安装被选择。请使用 py install 命令安装您期望的运行时，或配置您的默认标签。

未由 Python 安装管理器管理的预发布版和实验版安装可能会优先于稳定版本被选择。请配置您的默认标签，或卸载预发布版运行时，然后使用 py install 重新安装。

pythonw 或 pyw 启动的运行时与 python 或 py 不同。

点击开始菜单，打开"管理应用执行别名"，并确保您的 pythonw.exe 和 pyw.exe 别名与其他别名保持一致。

当我在终端中输入 pip 时，出现“命令未找到”错误。

您是否已激活虚拟环境？请在终端中运行 .venv\Scripts\activate 脚本以激活它。

该软件包可能已安装，但缺少生成的可执行文件。我们建议改用 python -m pip 命令，或者使用 python -m pip install --force pip 命令重新创建可执行文件，并显示需要添加到 PATH 的路径。这些脚本针对每个运行时是分开的，因此您可能需要添加多个路径。

4.2. 可嵌入的包

Added in version 3.5.

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

要安装嵌入式发行版，我们建议使用带 --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 包含进来并使用它进行自动更新。 通常，第三方包应该作为应用程序的一部分(“打包”)处理，以便开发人员在向用户提供更新之前能够确保与新版本兼容。

下面描述了这个发行版的两个推荐用例。

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 安装包

Added in version 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 选项，则此名称将包含已安装的特定版本。 子目录里面是一个包含 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. 自由线程版软件包

Added in version 3.13: （试验性功能）

备注

本节中描述的所有内容都是试验性的，它们预计会在未来的发布版中发生改变。

包含自由线程版二进制文件的包名称 python-freethreaded 对应 64 位版本，pythonx86-freethreaded 对应 32 位版本，pythonarm64-freethreaded 对应 ARM64 版本。 这些包同时包含 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.15 支持 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 模式

Added in version 3.7.

在 3.15.0a0 (unreleased) 版本发生变更: Python UTF-8 mode is now enabled by default (PEP 686).

Windows 仍然使用传统编码格式作为系统的编码格式 (ANSI 代码页)。 Python 使用它作为文本文件默认的编码格式 (即 locale.getencoding())。

这可能会造成问题，因为因特网和大多数 Unix 系统包括 WSL (Windows Subsystem for Linux) 广泛使用 UTF-8。

The Python UTF-8 Mode, enabled by default, can help by changing the default text encoding to UTF-8. When the UTF-8 mode is enabled, you can still use the system encoding (the ANSI Code Page) via the "mbcs" codec.

You can disable the Python UTF-8 Mode via the -X utf8=0 command line option, or the PYTHONUTF8=0 environment variable. See PYTHONUTF8 for disabling UTF-8 mode, and Python 安装管理器 for how to modify environment variables.

提示

Adding PYTHONUTF8={0,1} to the default environment variables will affect all Python 3.7+ applications on your system. If you have any Python 3.7+ applications which rely on the legacy system encoding, it is recommended to set the environment variable temporarily or use the -X utf8 command line option.

备注

即使在不启用 UTF-8 模式时，Windows 版的 Python 也会在以下情况中默认使用 UTF-8：

4.8. 查找模块

这些注释以详细的 Windows 注释对 sys.path 模块搜索路径的初始化 中的描述进行了补充。

当找不到 ._pth 文件时， sys.path 是如何在Windows上填充的：

  • 在开始时，添加一个空条目，该条目对应于当前目录。

  • 如果环境变量 PYTHONPATH 存在，如 环境变量 中所述，则接下来添加其条目。请注意，在Windows上，此变量中的路径必须用分号分隔，以区别于驱动器标识符中使用的冒号（ C:\ 等）。

  • 额外的 "应用程序路径" 可以作为子键被同时添加到注册表 HKEY_CURRENT_USER 和 HKEY_LOCAL_MACHINE 分支下的 \SOFTWARE\Python\PythonCore{version}\PythonPath 中。 以分号分隔的路径字符串作为默认值的子键将导致每个路径都被添加到 sys.path 中。 （请注意所有已知的安装程序都只使用 HKLM，因此 HKCU 通常为空。）

  • 如果设置了环境变量 PYTHONHOME ，则将其假定为 “Python 主目录” 。否则，主Python可执行文件的路径用于定位 “landmark 文件” （ Lib\os.py 或 pythonXY.zip ）以推断 ”Python 主目录“ 。如果找到了Python主目录，则基于该文件夹将相关的子目录添加到 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。

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

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

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

在 3.6 版本发生变更: 添加 ._pth 文件支持并从 pyvenv.cfg 中移除了 applocal 选项。

在 3.6 版本发生变更: 当与可执行文件直接相邻时将添加 pythonXX.zip 作为潜在的标志物。

自 3.6 版本弃用: 在 Modules (不是 PythonPath) 下的注册表中指定的模块可以通过 importlib.machinery.WindowsRegistryFinder 导入。 在 Windows 上此查找器在 3.6.0 及更早版本中被启用，但在将来可能需要显式地添加到 sys.meta_path。

4.9. 附加模块

尽管Python的目标是在所有平台中都可移植，但是Windows有一些独特的特性。在标准库和外部都有一些模块和代码片段在使用这些特性。

特定于Windows的标准模块记录在 Windows系统相关模块 中。

4.9.1. PyWin32

Mark Hammond 编写的 PyWin32 模块是一组用于高级 Windows 专属支持的模块。 这包括以下实用工具：

PythonWin 是PyWin32附带的一个示例MFC应用程序。它是一个内置调试器的可嵌入IDE。

参见

Win32 How Do I...?

Tim Golden 著

Python and COM

David 和 Paul Boddie 著

4.9.2. cx_Freeze

cx_Freeze 将 Python 脚本包装成可执行的 Windows 程序 (*.exe 文件)。 当你完成此操作后，你就可以分发你的应用程序而无需用户安装 Python。

4.10. 在Windows上编译Python

如果你想要自己编译 CPython，首先要做的是获取 源代码。 你可以下载最新发行版的源代码或是执行最新的 签出。

源代码树包含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.15 安装程序可供下载 - 32位和64位版本的各有两个。 web installer （网络安装包）是一个小的初始化工具，它将在安装过程中，根据需要自动下载所需的组件。 offline installer （离线安装包）内含默认安装所需的组件，可选择功能仍需要Internet连接下载。请参阅 免下载安装 以了解在安装过程中避免下载的其他方法。

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

../_images/win_installer.png

如果选择“Install Now（立即安装）”：

  • 您 不 需要成为管理员（除非需要对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 [directory]

预下载所有组件

/log [filename]

指定日志记录文件位置

所有其他选项都传递为 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的某些可选功能，如果选择安装这些功能可能需要Internet连接。为了避免这种需要，可以按需下载所有可能的组件，以创建一个完整的布局，该布局将不再需要internet连接，而不管所选择的特性是什么。请注意，此下载可能比要求的要大，但是如果要执行大量安装，则拥有本地缓存​​的副本非常有用。

从命令提示符执行以下命令以下载所有可能的必需文件。 请记得要将 python-3.9.0.exe 替换为安装程序的实际名称，并在单独的目录中创建子目录以避免同名文件间的冲突。

python-3.9.0.exe /layout [可选的目标目录]

您也可以指定 /quiet 选项来隐藏进度显示。

4.11.5. 修改安装

安装Python后，您可以通过Windows中的“程序和功能”工具添加或删除功能。选择Python条目并选择“卸载/更改”以在维护模式下打开安装程序。

“修改” 允许您通过修改复选框来添加或删除功能 - 未更改的复选框将不会安装或删除任何内容。在此模式下无法更改某些选项，例如安装目录；要修改这些，您需要完全删除然后重新安装Python。

“修复” 将使用当前设置验证应安装的所有文件，并替换已删除或修改的任何文件

“卸载” 将完全删除Python，但 Python 安装管理器 除外，它在“程序和功能”中有自己的条目。

4.11.6. 安装自由线程二进制文件

Added in version 3.13: （试验性功能）

备注

本节中描述的所有内容都是试验性的，它们预计会在未来的发布版中发生改变。

要安装启用了自由线程的预编译版二进制文件 (参见 PEP 703)，你应当选择 "Customize installation"。 在第二个选项页中包括了 "Download free-threaded binaries" 复选框。

../_images/win_install_freethreaded.png

选择此选项将下载并将额外的二进制文件安装到与 Python 主安装版本相同的目录下。 主可执行文件的名称为 python3.13t.exe，而其他二进制文件将带有 t 前缀或完整的 ABI 前缀。 Python 源文件和捆绑的第三方依赖将与主安装版本共享。

自由线程版将被注册为具有 3.13t 标签的常规 Python 安装版（并会按相应系统平台的惯例附带 -32 或 -arm64 后缀）。 这使得各种工具能够找到它，并使得 Python 安装管理器 能够支持 py.exe -3.13t。 请注意 launcher 会将 py.exe -3 (或 python3 shebang 行) 解读为“最新的 3.x 安装版”，这将使得自由线程版二进制文件优先于常规版，而 py.exe -3.13 则会使用常规版。 如果你要使用简短风格的选项，那么目前你应该选择不安装自由线程版二进制文件。

要在命令行中指定安装选项，请使用 Include_freethreaded=1。 请参阅 免下载安装 获取有关预先下载额外二进制文件供离线安装的指导。 包括调试符号和二进制文件的选项也同样适用于自由线程构建版。

自由线程版二进制文件也可 在 nuget.org 获取。

4.12. 针对 Windows 的 Python 启动器 (已弃用)

自 3.14 版本弃用: 启动器和本文档已被上文所述的 Python 安装管理器取代。保留这些内容只是暂时出于历史参考目的。

Added in version 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.15 ），您会注意到Python 3.15 启动 - 如果要启动 Python 3.7，尝试命令：

py -3.7

如果您想使用已安装的 Python 2 的最新版本，请尝试以下命令：

py -2

如果您看到以下错误，则表明您没有安装启动器：

'py' 不是内部或外部命令，也不是可运行的程序或批处理文件。

Tix 命令：

py --list

显示当前已安装的Python版本。

-x.y 参数是 -V:Company/Tag 参数的简短形式，它允许选择一个特定的 Python 运行时，包括可能来自于 python.org 以外地方的版本。 任何遵循 PEP 514 进行注册的运行时都将是可被发现的。 --list 命令将列出所有使用 -V: 格式的可用运行时。

当使用 -V: 参数时，指定 Company 将把选择限制到来自该提供方的运行时，而仅指定 Tag 将选择来自所有提供方的运行时。 请注意省略斜杠将会视作是一个 Tag:

# 选择任意带 '3.*' 标签的运行时
py -V:3

# 选择任何 'PythonCore' 发行的运行时
py -V:PythonCore/

# 选择 PythonCore 的最新 Python 3 运行时
py -V:PythonCore/3

该参数的简短形式 (-3) 将只选择来自核心 Python 发布版的运行时，而不选择其他分发版。 但是，完整形式 (-V:3) 则将选择来自任何版本的运行时。

Company 是在完整字符串上以大小写不敏感的方式进行匹配。 Tag 是在完整字符串或前缀上进行匹配，具体取决于下一个字符是点号还是连字符。 这将允许 -V:3.1 匹配 3.1-32，但不匹配 3.10。 Tag 是使用数字顺序进行排序的 (3.10 比 3.1 新)，但会按文本进行比较 (-V:3.01 将不匹配 3.1)。

4.12.1.2. 从虚拟环境

Added in version 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，其中命令 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。 如果激活了一个虚拟环境，则将忽略版本号并使用激活的环境。

Added in version 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 的情况。

The /usr/bin/env form of shebang line has one further special property. Before looking for installed Python interpreters, this form will search the executable PATH for a Python executable matching the name provided as the first argument. This corresponds to the behaviour of the Unix env program, which performs a PATH search. If an executable matching the first argument after the env command cannot be found, but the argument starts with python, it will be handled as described for the other virtual commands. The environment variable PYLAUNCHER_NO_SEARCH_PATH may be set (to any value) to skip this search of PATH.

无法匹配这些模式中任何一个的井号叹号行将在启动器的 .INI 文件 的 [commands] 一节中查找。 这可被用来以对你的系统来说有意义的方式处理某些命令。 命名的名称必须是一个单独的参数（在井号叹号行的可执行程序中不可有空格），而被替代的值则是该可执行程序的完整路径（在 .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。 同样的 .ini 文件还会被用于启动器的‘控制台’版本 (即 py.exe) 和‘窗口’版本 (即 pyw.exe)。

“应用程序目录”中指定的自定义优先于可执行文件旁边.ini文件的自定义，因此对启动程序旁边的.ini文件不具有写访问权限的用户可以覆盖该全局.ini文件中的命令。

4.12.4.2. 自定义默认的Python版本

在某些情况下，可以在命令中包含版本限定符，以指定命令将使用哪个Python版本。版本限定符以主版本号开头，可以选择后跟 ('.') 和次版本说明符。此外，可以通过添加 "-32" 或 “-64” 来指定是请求32位还是64位实现。

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

If no version qualifiers are found in a command, the environment variable PY_PYTHON can be set to specify the default version qualifier. If it is not set, the default is "3". The variable can specify any value that may be passed on the command line, such as "3", "3.7", "3.7-32" or "3.7-64". (Note that the "-64" option is only available with the launcher included with Python 3.7 or newer.)

如果没有找到次版本限定符，则可以设置环境变量 PY_PYTHON{major} （其中 {major} 是上面确定的当前主要版本限定符）以指定完整版本。如果没有找到这样的选项，启动器将枚举已安装的Python版本并使用为主要版本找到的最新次要版本，尽管不能保证，但该版本可能是该系列中最新安装的版本。

在安装了相同（major.minor）Python版本的32位和64位的64位Windows上，64位版本将始终是首选。对于启动程序的32位和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. 诊断

If an environment variable PYLAUNCHER_DEBUG is set (to any value), the launcher will print diagnostic information to stderr (i.e. to the console). While this information manages to be simultaneously verbose and terse, it should allow you to see what versions of Python were located, why a particular version was chosen and the exact command-line used to execute the target Python. It is primarily intended for testing and debugging.

4.12.6. 试运行

If an environment variable PYLAUNCHER_DRYRUN is set (to any value), the launcher will output the command it would have run, but will not actually launch Python. This may be useful for tools that want to use the launcher to detect and then launch Python directly. Note that the command written to standard output is always encoded using UTF-8, and may not render correctly in the console.

4.12.7. 按需安装

If an environment variable PYLAUNCHER_ALLOW_INSTALL is set (to any value), and the requested Python version is not installed but is available on the Microsoft Store, the launcher will attempt to install it. This may require user interaction to complete, and you may need to run the command again.

An additional PYLAUNCHER_ALWAYS_INSTALL variable causes the launcher to always try to install Python, even if it is detected. This is mainly intended for testing (and should be used with 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 但没有找到。