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 |