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