4. 在 Windows 上使用 Python¶
This document aims to give an overview of Windows-specific behaviour you should know about when using Python on Microsoft Windows.
Unlike most Unix systems and services, Windows does not include a system supported installation of Python. Instead, Python can be obtained from a number of distributors, including directly from the CPython team. Each Python distribution will have its own benefits and drawbacks, however, consistency with other tools you are using is generally a worthwhile benefit. Before committing to the process described here, we recommend investigating your existing tools to see if they can provide Python directly.
To obtain Python from the CPython team, use the Python Install Manager. This is a standalone tool that makes Python available as global commands on your Windows machine, integrates with the system, and supports updates over time. You can download the Python Install Manager from python.org/downloads or through the Microsoft Store app.
Once you have installed the Python Install Manager, the global python
command can be used from any terminal to launch your current latest version of
Python. This version may change over time as you add or remove different
versions, and the py list command will show which is current.
In general, we recommend that you create a virtual environment
for each project and run <env>\Scripts\Activate in your terminal to use it.
This provides isolation between projects, consistency over time, and ensures
that additional commands added by packages are also available in your session.
Create a virtual environment using python -m venv <env path>.
If the python or py commands do not seem to be working, please see the
Troubleshooting section below. There are
sometimes additional manual steps required to configure your PC.
Apart from using the Python install manager, Python can also be obtained as NuGet packages. See nuget.org 套件 below for more information on these packages.
The embeddable distros are minimal packages of Python suitable for embedding into larger applications. They can be installed using the Python install manager. See The embeddable package below for more information on these packages.
4.1. Python 安裝管理員¶
4.1.1. 安裝¶
The Python install manager can be installed from the Microsoft Store app or downloaded and installed from python.org/downloads. The two versions are identical.
To install through the Store, simply click "Install". After it has completed,
open a terminal and type python to get started.
To install the file downloaded from python.org, either double-click and select
"Install", or run Add-AppxPackage <path to MSIX> in Windows Powershell.
After installation, the python, py, and pymanager commands should be
available. If you have existing installations of Python, or you have modified
your PATH variable, you may need to remove them or undo the
modifications. See Troubleshooting for more help with fixing
non-working commands.
When you first install a runtime, you will likely be prompted to add a directory
to your PATH. This is optional, if you prefer to use the py
command, but is offered for those who prefer the full range of aliases (such
as python3.14.exe) to be available. The directory will be
%LocalAppData%\Python\bin by default, but may be customized by an
administrator. Click Start and search for "Edit environment variables for your
account" for the system settings page to add the path.
Each Python runtime you install will have its own directory for scripts. These
also need to be added to PATH if you want to use them.
The Python install manager will be automatically updated to new releases. This does not affect any installs of Python runtimes. Uninstalling the Python install manager does not uninstall any Python runtimes.
If you are not able to install an MSIX in your context, for example, you are using automated deployment software that does not support it, or are targeting Windows Server 2019, please see 進階安裝 below for more information.
4.1.2. 基本使用¶
The recommended command for launching Python is python, which will either
launch the version requested by the script being launched, an active virtual
environment, or the default installed version, which will be the latest stable
release unless configured otherwise. If no version is specifically requested and
no runtimes are installed at all, the current latest release will be installed
automatically.
For all scenarios involving multiple runtime versions, the recommended command
is py. This may be used anywhere in place of python or the older
py.exe launcher. By default, py matches the behaviour of python, but
also allows command line options to select a specific version as well as
subcommands to manage installations. These are detailed below.
Because the py command may already be taken by the previous version, there
is also an unambiguous pymanager command. Scripted installs that are
intending to use Python install manager should consider using pymanager, due
to the lower chance of encountering a conflict with existing installs. The only
difference between the two commands is when running without any arguments:
py will launch your default interpreter, while pymanager will display
help (pymanager exec ... provides equivalent behaviour to py ...).
Each of these commands also has a windowed version that avoids creating a
console window. These are pyw, pythonw and pymanagerw. A python3
command is also included that mimics the python command. It is intended to
catch accidental uses of the typical POSIX command on Windows, but is not meant
to be widely used or recommended.
To launch your default runtime, run python or py with the arguments you
want to be passed to the runtime (such as script files or the module to launch):
$> py
...
$> python my-script.py
...
$> py -m this
...
The default runtime can be overridden with the PYTHON_MANAGER_DEFAULT
environment variable, or a configuration file. See 設定 for
information about configuration settings.
To launch a specific runtime, the py command accepts a -V:<TAG> option.
This option must be specified before any others. The tag is part or all of the
identifier for the runtime; for those from the CPython team, it looks like the
version, potentially with the platform. For compatibility, the V: may be
omitted in cases where the tag refers to an official release and starts with
3.
$> py -V:3.14 ...
$> py -V:3-arm64 ...
Runtimes from other distributors may require the company to be included as
well. This should be separated from the tag by a slash, and may be a prefix.
Specifying the company is optional when it is PythonCore, and specifying the
tag is optional (but not the slash) when you want the latest release from a
specific company.
$> py -V:Distributor\1.0 ...
$> py -V:distrib/ ...
If no version is specified, but a script file is passed, the script will be inspected for a shebang line. This is a special format for the first line in a file that allows overriding the command. See Shebang lines for more information. When there is no shebang line, or it cannot be resolved, the script will be launched with the default runtime.
If you are running in an active virtual environment, have not requested a
particular version, and there is no shebang line, the default runtime will be
that virtual environment. In this scenario, the python command was likely
already overridden and none of these checks occurred. However, this behaviour
ensures that the py command can be used interchangeably.
When no runtimes are installed, any launch command will try to install the
requested version and launch it. However, after any version is installed, only
the py exec ... and pymanager exec ... commands will install if the
requested version is absent. Other forms of commands will display an error and
direct you to use py install first.
4.1.3. Command help¶
The py help command will display the full list of supported commands, along
with their options. Any command may be passed the -? option to display its
help, or its name passed to py help.
$> py help
$> py help install
$> py install /?
All commands support some common options, which will be shown by py help.
These options must be specified after any subcommand. Specifying -v or
--verbose will increase the amount of output shown, and -vv will
increase it further for debugging purposes. Passing -q or --quiet will
reduce output, and -qq will reduce it further.
The --config=<PATH> option allows specifying a configuration file to
override multiple settings at once. See 設定 below for more
information about these files.
4.1.4. 列出 runtimes¶
$> py list [-f=|--format=<FMT>] [-1|--one] [--online|-s=|--source=<URL>] [<TAG>...]
The list of installed runtimes can be seen using py list. A filter may be
added in the form of one or more tags (with or without company specifier), and
each may include a <, <=, >= or > prefix to restrict to a range.
A range of formats are supported, and can be passed as the --format=<FMT> or
-f <FMT> option. Formats include table (a user friendly table view),
csv (comma-separated table), json (a single JSON blob), jsonl (one
JSON blob per result), exe (just the executable path), prefix (just the
prefix path).
The --one or -1 option only displays a single result. If the default
runtime is included, it will be the one. Otherwise, the "best" result is shown
("best" is deliberately vaguely defined, but will usually be the most recent
version). The result shown by py list --one <TAG> will match the runtime
that would be launched by py -V:<TAG>.
The --only-managed option excludes results that were not installed by the
Python install manager. This is useful when determining which runtimes may be
updated or uninstalled through the py command.
The --online option is short for passing --source=<URL> with the default
source. Passing either of these options will search the online index for
runtimes that can be installed. The result shown by py list --online --one
<TAG> will match the runtime that would be installed by py install <TAG>.
$> py list --online 3.14
For compatibility with the old launcher, the --list, --list-paths,
-0 and -0p commands (e.g. py -0p) are retained. They do not allow
additional options, and will produce legacy formatted output.
4.1.5. 安裝 runtimes¶
$> py install [-s=|--source=<URL>] [-f|--force] [-u|--update] [--dry-run] [<TAG>...]
New runtime versions may be added using py install. One or more tags may be
specified, and the special tag default may be used to select the default.
Ranges are not supported for installation.
The --source=<URL> option allows overriding the online index that is used to
obtain runtimes. This may be used with an offline index, as shown in
離線安裝.
Passing --force will ignore any cached files and remove any existing install
to replace it with the specified one.
Passing --update will replace existing installs if the new version is newer.
Otherwise, they will be left. If no tags are provided with --update, all
installs managed by the Python install manager will be updated if newer versions
are available. Updates will remove any modifications made to the install,
including globally installed packages, but virtual environments will continue to
work.
Passing --dry-run will generate output and logs, but will not modify any
installs.
Passing --refresh will update all registrations for installed runtimes. This
will recreate Start menu shortcuts, registry keys, and global aliases (such as
python3.14.exe or for any installed scripts). These are automatically
refreshed on installation of any runtime, but may need to be manually refreshed
after installing packages.
In addition to the above options, the --target option will extract the
runtime to the specified directory instead of doing a normal install.
This is useful for embedding runtimes into larger applications.
Unlike a normal install, py will not be aware of the extracted runtime,
and no Start menu or other shortcuts will be created.
To launch the runtime, directly execute the main executable (typically
python.exe) in the target directory.
$> py install ... [-t=|--target=<PATH>] <TAG>
The py exec command will install the requested runtime if it is not already
present. This is controlled by the automatic_install configuration
(PYTHON_MANAGER_AUTOMATIC_INSTALL), and is enabled by default.
If no runtimes are available at all, all launch commands will do an automatic
install if the configuration setting allows. This is to ensure a good experience
for new users, but should not generally be relied on rather than using the
py exec command or explicit install commands.
4.1.6. 離線安裝¶
To perform offline installs of Python, you will need to first create an offline index on a machine that has network access.
$> py install --download=<PATH> ... <TAG>...
The --download=<PATH> option will download the packages for the listed tags
and create a directory containing them and an index.json file suitable for
later installation. This entire directory can be moved to the offline machine
and used to install one or more of the bundled runtimes:
$> py install --source="<PATH>\index.json" <TAG>...
The Python install manager can be installed by downloading its installer and moving it to another machine before installing.
Alternatively, the ZIP files in an offline index directory can simply be transferred to another machine and extracted. This will not register the install in any way, and so it must be launched by directly referencing the executables in the extracted directory, but it is sometimes a preferable approach in cases where installing the Python install manager is not possible or convenient.
In this way, Python runtimes can be installed and managed on a machine without access to the internet.
4.1.7. 解除安裝 runtimes¶
$> py uninstall [-y|--yes] <TAG>...
Runtimes may be removed using the py uninstall command. One or more tags
must be specified. Ranges are not supported here.
The --yes option bypasses the confirmation prompt before uninstalling.
Instead of passing tags individually, the --purge option may be specified.
This will remove all runtimes managed by the Python install manager, including
cleaning up the Start menu, registry, and any download caches. Runtimes that
were not installed by the Python install manager will not be impacted, and
neither will manually created configuration files.
$> py uninstall [-y|--yes] --purge
The Python install manager can be uninstalled through the Windows "Installed
apps" settings page. This does not remove any runtimes, and they will still be
usable, though the global python and py commands will be removed.
Reinstalling the Python install manager will allow you to manage these runtimes
again. To completely clean up all Python runtimes, run with --purge before
uninstalling the Python install manager.
4.1.8. 設定¶
Python install manager is configured with a hierarchy of configuration files, environment variables, command-line options, and registry settings. In general, configuration files have the ability to configure everything, including the location of other configuration files, while registry settings are administrator-only and will override configuration files. Command-line options override all other settings, but not every option is available.
This section will describe the defaults, but be aware that modified or overridden installs may resolve settings differently.
A global configuration file may be configured by an administrator, and would be
read first. The user configuration file is stored at
%AppData%\Python\pymanager.json
(note that this location is under Roaming, not Local) and is read next,
overwriting any settings from earlier files. An additional configuration file
may be specified as the PYTHON_MANAGER_CONFIG environment variable or the
--config command line option (but not both).
These locations may be modified by administrative customization options listed
later.
The following settings are those that are considered likely to be modified in normal use. Later sections list those that are intended for administrative customization.
Standard configuration options
Config Key |
Environment Variable |
描述 |
|---|---|---|
|
|
The preferred default version to launch or install. By default, this is interpreted as the most recent non-prerelease version from the CPython team. |
|
|
The preferred default platform to launch or install.
This is treated as a suffix to the specified tag, such that |
|
|
The location where log files are written.
By default, |
|
|
True to allow automatic installs when using |
|
|
True to allow listing and launching runtimes that were not installed by the Python install manager, or false to exclude them. By default, true. |
|
|
True to allow shebangs in |
|
|
Set the default level of output (0-50). By default, 20. Lower values produce more output. The environment variables are boolean, and may produce additional output during startup that is later suppressed by other configuration. |
|
|
True to confirm certain actions before taking them (such as uninstall), or false to skip the confirmation. By default, true. |
|
|
Override the index feed to obtain new installs from. |
|
(none) |
True to generate global commands for installed packages (such as
|
|
|
Specify the default format used by the |
|
(none) |
Specify the root directory that runtimes will be installed into. If you change this setting, previously installed runtimes will not be usable unless you move them to the new location. |
|
(none) |
Specify the directory where global commands (such as |
|
(none) |
Specify the directory where downloaded files are stored. This directory is a temporary cache, and can be cleaned up from time to time. |
Dotted names should be nested inside JSON objects, for example, list.format
would be specified as {"list": {"format": "table"}}.
4.1.9. Shebang lines¶
If the first line of a script file starts with #!, it is known as a
"shebang" line. Linux and other Unix like operating systems have native
support for such lines and they are commonly used on such systems to indicate
how a script should be executed. The python and py commands allow the
same facilities to be used with Python scripts on Windows.
To allow shebang lines in Python scripts to be portable between Unix and Windows, a number of 'virtual' commands are supported to specify which interpreter to use. The supported virtual commands are:
/usr/bin/env <ALIAS>/usr/bin/env -S <ALIAS>/usr/bin/<ALIAS>/usr/local/bin/<ALIAS><ALIAS>
For example, if the first line of your script starts with
#! /usr/bin/python
The default Python or an active virtual environment will be located and used.
As many Python scripts written to work on Unix will already have this line,
you should find these scripts can be used by the launcher without modification.
If you are writing a new script on Windows which you hope will be useful on
Unix, you should use one of the shebang lines starting with /usr.
Any of the above virtual commands can have <ALIAS> replaced by an alias from
an installed runtime. That is, any command generated in the global aliases
directory (which you may have added to your PATH environment variable)
can be used in a shebang, even if it is not on your PATH. This allows
the use of shebangs like /usr/bin/python3.12 to select a particular runtime.
If no runtimes are installed, or if automatic installation is enabled, the requested runtime will be installed if necessary. See 設定 for information about configuration settings.
The /usr/bin/env form of shebang line will also search the PATH
environment variable for unrecognized commands. This corresponds to the
behaviour of the Unix env program, which performs the same search, but
prefers launching known Python commands. A warning may be displayed when
searching for arbitrary executables, and this search may be disabled by the
shebang_can_run_anything configuration option.
Shebang lines that do not match any of patterns are treated as Windows
executable paths that are absolute or relative to the directory containing the
script file. This is a convenience for Windows-only scripts, such as those
generated by an installer, since the behavior is not compatible with Unix-style
shells. These paths may be quoted, and may include multiple arguments, after
which the path to the script and any additional arguments will be appended.
This functionality may be disabled by the shebang_can_run_anything
configuration option.
備註
The behaviour of shebangs in the Python install manager is subtly different
from the previous py.exe launcher, and the old configuration options no
longer apply. If you are specifically reliant on the old behaviour or
configuration, we recommend installing the legacy launcher. The legacy
launcher's py command will override PyManager's one by default, and you
will need to use pymanager commands for installing and uninstalling.
4.1.10. 進階安裝¶
For situations where an MSIX cannot be installed, such as some older
administrative distribution platforms, there is an MSI available from the
python.org downloads page. This MSI has no user interface, and can only perform
per-machine installs to its default location in Program Files. It will attempt
to modify the system PATH environment variable to include this install
location, but be sure to validate this on your configuration.
備註
Windows Server 2019 is the only version of Windows that CPython supports that does not support MSIX. For Windows Server 2019, you should use the MSI.
Be aware that the MSI package does not bundle any runtimes, and so is not suitable for installs into offline environments without also creating an offline install index. See 離線安裝 and Administrative configuration for information on handling these scenarios.
Runtimes installed by the MSI are shared with those installed by the MSIX, and
are all per-user only. The Python install manager does not support installing
runtimes per-machine. To emulate a per-machine install, you can use py install
--target=<shared location> as administrator and add your own system-wide
modifications to PATH, the registry, or the Start menu.
When the MSIX is installed, but commands are not available in the PATH
environment variable, they can be found under
%LocalAppData%\Microsoft\WindowsApps\PythonSoftwareFoundation.PythonManager_3847v3x7pw1km
or
%LocalAppData%\Microsoft\WindowsApps\PythonSoftwareFoundation.PythonManager_qbz5n2kfra8p0,
depending on whether it was installed from python.org or through the Windows
Store. Attempting to run the executable directly from Program Files is not
recommended.
To programmatically install the Python install manager, it is easiest to use WinGet, which is included with all supported versions of Windows:
$> winget install 9NQ7512CXL7T -e --accept-package-agreements --disable-interactivity
# Optionally run the configuration checker and accept all changes
$> py install --configure -y
To download the Python install manager and install on another machine, the
following WinGet command will download the required files from the Store to your
Downloads directory (add -d <location> to customize the output location).
This also generates a YAML file that appears to be unnecessary, as the
downloaded MSIX can be installed by launching or using the commands below.
$> winget download 9NQ7512CXL7T -e --skip-license --accept-package-agreements --accept-source-agreements
To programmatically install or uninstall an MSIX using only PowerShell, the Add-AppxPackage and Remove-AppxPackage PowerShell cmdlets are recommended:
$> Add-AppxPackage C:\Downloads\python-manager-25.0.msix
...
$> Get-AppxPackage PythonSoftwareFoundation.PythonManager | Remove-AppxPackage
The latest release can be downloaded and installed by Windows by passing the AppInstaller file to the Add-AppxPackage command. This installs using the MSIX on python.org, and is only recommended for cases where installing via the Store (interactively or using WinGet) is not possible.
$> Add-AppxPackage -AppInstallerFile https://www.python.org/ftp/python/pymanager/pymanager.appinstaller
Other tools and APIs may also be used to provision an MSIX package for all users on a machine, but Python does not consider this a supported scenario. We suggest looking into the PowerShell Add-AppxProvisionedPackage cmdlet, the native Windows PackageManager class, or the documentation and support for your deployment tool.
Regardless of the install method, users will still need to install their own copies of Python itself, as there is no way to trigger those installs without being a logged in user. When using the MSIX, the latest version of Python will be available for all users to install without network access.
Note that the MSIX downloadable from the Store and from the Python website are subtly different and cannot be installed at the same time. Wherever possible, we suggest using the above WinGet commands to download the package from the Store to reduce the risk of setting up conflicting installs. There are no licensing restrictions on the Python install manager that would prevent using the Store package in this way.
4.1.11. Administrative configuration¶
There are a number of options that may be useful for administrators to override configuration of the Python install manager. These can be used to provide local caching, disable certain shortcut types, override bundled content. All of the above configuration options may be set, as well as those below.
Configuration options may be overridden in the registry by setting values under
HKEY_LOCAL_MACHINE\Software\Policies\Python\PyManager, where the
value name matches the configuration key and the value type is REG_SZ. Note
that this key can itself be customized, but only by modifying the core config
file distributed with the Python install manager. We recommend, however, that
registry values are used only to set base_config to a JSON file containing
the full set of overrides. Registry key overrides will replace any other
configured setting, while base_config allows users to further modify
settings they may need.
Note that most settings with environment variables support those variables
because their default setting specifies the variable. If you override them, the
environment variable will no longer work, unless you override it with another
one. For example, the default value of confirm is literally
%PYTHON_MANAGER_CONFIRM%, which will resolve the variable at load time. If
you override the value to yes, then the environment variable will no longer
be used. If you override the value to %CONFIRM%, then that environment
variable will be used instead.
Configuration settings that are paths are interpreted as relative to the directory containing the configuration file that specified them.
Administrative configuration options
Config Key |
描述 |
|---|---|
|
The highest priority configuration file to read. Note that only the built-in configuration file and the registry can modify this setting. |
|
The second configuration file to read. |
|
The third configuration file to read. |
|
Registry location to check for overrides. Note that only the built-in configuration file can modify this setting. |
|
Read-only directory containing locally cached files. |
|
Path or URL to an index to consult when the main index cannot be accessed. |
|
Comma-separated list of shortcut kinds to allow (e.g. |
|
Comma-separated list of shortcut kinds to exclude (e.g. |