| 1 |
.. highlight:: none |
| 2 |
|
| 3 |
.. _python.org/downloads: https://www.python.org/downloads/ |
| 4 |
|
| 5 |
.. _Microsoft Store app: https://apps.microsoft.com/detail/9NQ7512CXL7T |
| 6 |
|
| 7 |
.. _legacy launcher: https://www.python.org/ftp/python/3.14.0/win32/launcher.msi |
| 8 |
|
| 9 |
.. _using-on-windows: |
| 10 |
|
| 11 |
************************* |
| 12 |
Using Python on Windows |
| 13 |
************************* |
| 14 |
|
| 15 |
.. sectionauthor:: Steve Dower <[email protected]> |
| 16 |
|
| 17 |
This document aims to give an overview of Windows-specific behaviour you should |
| 18 |
know about when using Python on Microsoft Windows. |
| 19 |
|
| 20 |
Unlike most Unix systems and services, Windows does not include a system |
| 21 |
supported installation of Python. Instead, Python can be obtained from a number |
| 22 |
of distributors, including directly from the CPython team. Each Python |
| 23 |
distribution will have its own benefits and drawbacks, however, consistency with |
| 24 |
other tools you are using is generally a worthwhile benefit. Before committing |
| 25 |
to the process described here, we recommend investigating your existing tools to |
| 26 |
see if they can provide Python directly. |
| 27 |
|
| 28 |
To obtain Python from the CPython team, use the Python Install Manager. This |
| 29 |
is a standalone tool that makes Python available as global commands on your |
| 30 |
Windows machine, integrates with the system, and supports updates over time. You |
| 31 |
can download the Python Install Manager from `python.org/downloads`_ or through |
| 32 |
the `Microsoft Store app`_. |
| 33 |
|
| 34 |
Once you have installed the Python Install Manager, the global ``python`` |
| 35 |
command can be used from any terminal to launch your current latest version of |
| 36 |
Python. This version may change over time as you add or remove different |
| 37 |
versions, and the ``py list`` command will show which is current. |
| 38 |
|
| 39 |
In general, we recommend that you create a :ref:`virtual environment <tut-venv>` |
| 40 |
for each project and run ``<env>\Scripts\Activate`` in your terminal to use it. |
| 41 |
This provides isolation between projects, consistency over time, and ensures |
| 42 |
that additional commands added by packages are also available in your session. |
| 43 |
Create a virtual environment using ``python -m venv <env path>``. |
| 44 |
|
| 45 |
If the ``python`` or ``py`` commands do not seem to be working, please see the |
| 46 |
:ref:`Troubleshooting <pymanager-troubleshoot>` section below. There are |
| 47 |
sometimes additional manual steps required to configure your PC. |
| 48 |
|
| 49 |
Apart from using the Python install manager, Python can also be obtained as |
| 50 |
NuGet packages. See :ref:`windows-nuget` below for more information on these |
| 51 |
packages. |
| 52 |
|
| 53 |
The embeddable distros are minimal packages of Python suitable for embedding |
| 54 |
into larger applications. They can be installed using the Python install |
| 55 |
manager. See :ref:`windows-embeddable` below for more information on these |
| 56 |
packages. |
| 57 |
|
| 58 |
|
| 59 |
.. _pymanager: |
| 60 |
.. _windows-store: |
| 61 |
.. _setting-envvars: |
| 62 |
.. _windows-path-mod: |
| 63 |
.. _launcher: |
| 64 |
|
| 65 |
Python install manager |
| 66 |
====================== |
| 67 |
|
| 68 |
Installation |
| 69 |
------------ |
| 70 |
|
| 71 |
The Python install manager can be installed from the `Microsoft Store app`_ |
| 72 |
or downloaded and installed from `python.org/downloads`_. The two versions are |
| 73 |
identical. |
| 74 |
|
| 75 |
To install through the Store, simply click "Install". After it has completed, |
| 76 |
open a terminal and type ``python`` to get started. |
| 77 |
|
| 78 |
To install the file downloaded from python.org, either double-click and select |
| 79 |
"Install", or run ``Add-AppxPackage <path to MSIX>`` in Windows Powershell. |
| 80 |
|
| 81 |
After installation, the ``python``, ``py``, and ``pymanager`` commands should be |
| 82 |
available. If you have existing installations of Python, or you have modified |
| 83 |
your :envvar:`PATH` variable, you may need to remove them or undo the |
| 84 |
modifications. See :ref:`pymanager-troubleshoot` for more help with fixing |
| 85 |
non-working commands. |
| 86 |
|
| 87 |
When you first install a runtime, you will likely be prompted to add a directory |
| 88 |
to your :envvar:`PATH`. This is optional, if you prefer to use the ``py`` |
| 89 |
command, but is offered for those who prefer the full range of aliases (such |
| 90 |
as ``python3.14.exe``) to be available. The directory will be |
| 91 |
:file:`%LocalAppData%\\Python\\bin` by default, but may be customized by an |
| 92 |
administrator. Click Start and search for "Edit environment variables for your |
| 93 |
account" for the system settings page to add the path. |
| 94 |
|
| 95 |
Each Python runtime you install will have its own directory for scripts. These |
| 96 |
also need to be added to :envvar:`PATH` if you want to use them. |
| 97 |
|
| 98 |
The Python install manager will be automatically updated to new releases. This |
| 99 |
does not affect any installs of Python runtimes. Uninstalling the Python install |
| 100 |
manager does not uninstall any Python runtimes. |
| 101 |
|
| 102 |
If you are not able to install an MSIX in your context, for example, you are |
| 103 |
using automated deployment software that does not support it, or are targeting |
| 104 |
Windows Server 2019, please see :ref:`pymanager-advancedinstall` below for more |
| 105 |
information. |
| 106 |
|
| 107 |
|
| 108 |
Basic use |
| 109 |
--------- |
| 110 |
|
| 111 |
The recommended command for launching Python is ``python``, which will either |
| 112 |
launch the version requested by the script being launched, an active virtual |
| 113 |
environment, or the default installed version, which will be the latest stable |
| 114 |
release unless configured otherwise. If no version is specifically requested and |
| 115 |
no runtimes are installed at all, the current latest release will be installed |
| 116 |
automatically. |
| 117 |
|
| 118 |
For all scenarios involving multiple runtime versions, the recommended command |
| 119 |
is ``py``. This may be used anywhere in place of ``python`` or the older |
| 120 |
``py.exe`` launcher. By default, ``py`` matches the behaviour of ``python``, but |
| 121 |
also allows command line options to select a specific version as well as |
| 122 |
subcommands to manage installations. These are detailed below. |
| 123 |
|
| 124 |
Because the ``py`` command may already be taken by the previous version, there |
| 125 |
is also an unambiguous ``pymanager`` command. Scripted installs that are |
| 126 |
intending to use Python install manager should consider using ``pymanager``, due |
| 127 |
to the lower chance of encountering a conflict with existing installs. The only |
| 128 |
difference between the two commands is when running without any arguments: |
| 129 |
``py`` will launch your default interpreter, while ``pymanager`` will display |
| 130 |
help (``pymanager exec ...`` provides equivalent behaviour to ``py ...``). |
| 131 |
|
| 132 |
Each of these commands also has a windowed version that avoids creating a |
| 133 |
console window. These are ``pyw``, ``pythonw`` and ``pymanagerw``. A ``python3`` |
| 134 |
command is also included that mimics the ``python`` command. It is intended to |
| 135 |
catch accidental uses of the typical POSIX command on Windows, but is not meant |
| 136 |
to be widely used or recommended. |
| 137 |
|
| 138 |
To launch your default runtime, run ``python`` or ``py`` with the arguments you |
| 139 |
want to be passed to the runtime (such as script files or the module to launch): |
| 140 |
|
| 141 |
.. code:: |
| 142 |
|
| 143 |
$> py |
| 144 |
... |
| 145 |
$> python my-script.py |
| 146 |
... |
| 147 |
$> py -m this |
| 148 |
... |
| 149 |
|
| 150 |
The default runtime can be overridden with the :envvar:`PYTHON_MANAGER_DEFAULT` |
| 151 |
environment variable, or a configuration file. See :ref:`pymanager-config` for |
| 152 |
information about configuration settings. |
| 153 |
|
| 154 |
To launch a specific runtime, the ``py`` command accepts a ``-V:<TAG>`` option. |
| 155 |
This option must be specified before any others. The tag is part or all of the |
| 156 |
identifier for the runtime; for those from the CPython team, it looks like the |
| 157 |
version, potentially with the platform. For compatibility, the ``V:`` may be |
| 158 |
omitted in cases where the tag refers to an official release and starts with |
| 159 |
``3``. |
| 160 |
|
| 161 |
.. code:: |
| 162 |
|
| 163 |
$> py -V:3.14 ... |
| 164 |
$> py -V:3-arm64 ... |
| 165 |
|
| 166 |
Runtimes from other distributors may require the *company* to be included as |
| 167 |
well. This should be separated from the tag by a slash, and may be a prefix. |
| 168 |
Specifying the company is optional when it is ``PythonCore``, and specifying the |
| 169 |
tag is optional (but not the slash) when you want the latest release from a |
| 170 |
specific company. |
| 171 |
|
| 172 |
.. code:: |
| 173 |
|
| 174 |
$> py -V:Distributor\1.0 ... |
| 175 |
$> py -V:distrib/ ... |
| 176 |
|
| 177 |
If no version is specified, but a script file is passed, the script will be |
| 178 |
inspected for a *shebang line*. This is a special format for the first line in |
| 179 |
a file that allows overriding the command. See :ref:`pymanager-shebang` for more |
| 180 |
information. When there is no shebang line, or it cannot be resolved, the script |
| 181 |
will be launched with the default runtime. |
| 182 |
|
| 183 |
If you are running in an active virtual environment, have not requested a |
| 184 |
particular version, and there is no shebang line, the default runtime will be |
| 185 |
that virtual environment. In this scenario, the ``python`` command was likely |
| 186 |
already overridden and none of these checks occurred. However, this behaviour |
| 187 |
ensures that the ``py`` command can be used interchangeably. |
| 188 |
|
| 189 |
When no runtimes are installed, any launch command will try to install the |
| 190 |
requested version and launch it. However, after any version is installed, only |
| 191 |
the ``py exec ...`` and ``pymanager exec ...`` commands will install if the |
| 192 |
requested version is absent. Other forms of commands will display an error and |
| 193 |
direct you to use ``py install`` first. |
| 194 |
|
| 195 |
|
| 196 |
Command help |
| 197 |
------------ |
| 198 |
|
| 199 |
The ``py help`` command will display the full list of supported commands, along |
| 200 |
with their options. Any command may be passed the ``-?`` option to display its |
| 201 |
help, or its name passed to ``py help``. |
| 202 |
|
| 203 |
.. code:: |
| 204 |
|
| 205 |
$> py help |
| 206 |
$> py help install |
| 207 |
$> py install /? |
| 208 |
|
| 209 |
|
| 210 |
All commands support some common options, which will be shown by ``py help``. |
| 211 |
These options must be specified after any subcommand. Specifying ``-v`` or |
| 212 |
``--verbose`` will increase the amount of output shown, and ``-vv`` will |
| 213 |
increase it further for debugging purposes. Passing ``-q`` or ``--quiet`` will |
| 214 |
reduce output, and ``-qq`` will reduce it further. |
| 215 |
|
| 216 |
The ``--config=<PATH>`` option allows specifying a configuration file to |
| 217 |
override multiple settings at once. See :ref:`pymanager-config` below for more |
| 218 |
information about these files. |
| 219 |
|
| 220 |
|
| 221 |
Listing runtimes |
| 222 |
---------------- |
| 223 |
|
| 224 |
.. code:: |
| 225 |
|
| 226 |
$> py list [-f=|--format=<FMT>] [-1|--one] [--online|-s=|--source=<URL>] [<TAG>...] |
| 227 |
|
| 228 |
The list of installed runtimes can be seen using ``py list``. A filter may be |
| 229 |
added in the form of one or more tags (with or without company specifier), and |
| 230 |
each may include a ``<``, ``<=``, ``>=`` or ``>`` prefix to restrict to a range. |
| 231 |
|
| 232 |
A range of formats are supported, and can be passed as the ``--format=<FMT>`` or |
| 233 |
``-f <FMT>`` option. Formats include ``table`` (a user friendly table view), |
| 234 |
``csv`` (comma-separated table), ``json`` (a single JSON blob), ``jsonl`` (one |
| 235 |
JSON blob per result), ``exe`` (just the executable path), ``prefix`` (just the |
| 236 |
prefix path). |
| 237 |
|
| 238 |
The ``--one`` or ``-1`` option only displays a single result. If the default |
| 239 |
runtime is included, it will be the one. Otherwise, the "best" result is shown |
| 240 |
("best" is deliberately vaguely defined, but will usually be the most recent |
| 241 |
version). The result shown by ``py list --one <TAG>`` will match the runtime |
| 242 |
that would be launched by ``py -V:<TAG>``. |
| 243 |
|
| 244 |
The ``--only-managed`` option excludes results that were not installed by the |
| 245 |
Python install manager. This is useful when determining which runtimes may be |
| 246 |
updated or uninstalled through the ``py`` command. |
| 247 |
|
| 248 |
The ``--online`` option is short for passing ``--source=<URL>`` with the default |
| 249 |
source. Passing either of these options will search the online index for |
| 250 |
runtimes that can be installed. The result shown by ``py list --online --one |
| 251 |
<TAG>`` will match the runtime that would be installed by ``py install <TAG>``. |
| 252 |
|
| 253 |
.. code:: |
| 254 |
|
| 255 |
$> py list --online 3.14 |
| 256 |
|
| 257 |
For compatibility with the old launcher, the ``--list``, ``--list-paths``, |
| 258 |
``-0`` and ``-0p`` commands (e.g. ``py -0p``) are retained. They do not allow |
| 259 |
additional options, and will produce legacy formatted output. |
| 260 |
|
| 261 |
|
| 262 |
Installing runtimes |
| 263 |
------------------- |
| 264 |
|
| 265 |
.. code:: |
| 266 |
|
| 267 |
$> py install [-s=|--source=<URL>] [-f|--force] [-u|--update] [--dry-run] [<TAG>...] |
| 268 |
|
| 269 |
New runtime versions may be added using ``py install``. One or more tags may be |
| 270 |
specified, and the special tag ``default`` may be used to select the default. |
| 271 |
Ranges are not supported for installation. |
| 272 |
|
| 273 |
The ``--source=<URL>`` option allows overriding the online index that is used to |
| 274 |
obtain runtimes. This may be used with an offline index, as shown in |
| 275 |
:ref:`pymanager-offline`. |
| 276 |
|
| 277 |
Passing ``--force`` will ignore any cached files and remove any existing install |
| 278 |
to replace it with the specified one. |
| 279 |
|
| 280 |
Passing ``--update`` will replace existing installs if the new version is newer. |
| 281 |
Otherwise, they will be left. If no tags are provided with ``--update``, all |
| 282 |
installs managed by the Python install manager will be updated if newer versions |
| 283 |
are available. Updates will remove any modifications made to the install, |
| 284 |
including globally installed packages, but virtual environments will continue to |
| 285 |
work. |
| 286 |
|
| 287 |
Passing ``--dry-run`` will generate output and logs, but will not modify any |
| 288 |
installs. |
| 289 |
|
| 290 |
Passing ``--refresh`` will update all registrations for installed runtimes. This |
| 291 |
will recreate Start menu shortcuts, registry keys, and global aliases (such as |
| 292 |
``python3.14.exe`` or for any installed scripts). These are automatically |
| 293 |
refreshed on installation of any runtime, but may need to be manually refreshed |
| 294 |
after installing packages. |
| 295 |
|
| 296 |
In addition to the above options, the ``--target`` option will extract the |
| 297 |
runtime to the specified directory instead of doing a normal install. |
| 298 |
This is useful for embedding runtimes into larger applications. |
| 299 |
Unlike a normal install, ``py`` will not be aware of the extracted runtime, |
| 300 |
and no Start menu or other shortcuts will be created. |
| 301 |
To launch the runtime, directly execute the main executable (typically |
| 302 |
``python.exe``) in the target directory. |
| 303 |
|
| 304 |
.. code:: |
| 305 |
|
| 306 |
$> py install ... [-t=|--target=<PATH>] <TAG> |
| 307 |
|
| 308 |
The ``py exec`` command will install the requested runtime if it is not already |
| 309 |
present. This is controlled by the ``automatic_install`` configuration |
| 310 |
(:envvar:`PYTHON_MANAGER_AUTOMATIC_INSTALL`), and is enabled by default. |
| 311 |
If no runtimes are available at all, all launch commands will do an automatic |
| 312 |
install if the configuration setting allows. This is to ensure a good experience |
| 313 |
for new users, but should not generally be relied on rather than using the |
| 314 |
``py exec`` command or explicit install commands. |
| 315 |
|
| 316 |
|
| 317 |
.. _pymanager-offline: |
| 318 |
|
| 319 |
Offline installs |
| 320 |
---------------- |
| 321 |
|
| 322 |
To perform offline installs of Python, you will need to first create an offline |
| 323 |
index on a machine that has network access. |
| 324 |
|
| 325 |
.. code:: |
| 326 |
|
| 327 |
$> py install --download=<PATH> ... <TAG>... |
| 328 |
|
| 329 |
The ``--download=<PATH>`` option will download the packages for the listed tags |
| 330 |
and create a directory containing them and an ``index.json`` file suitable for |
| 331 |
later installation. This entire directory can be moved to the offline machine |
| 332 |
and used to install one or more of the bundled runtimes: |
| 333 |
|
| 334 |
.. code:: |
| 335 |
|
| 336 |
$> py install --source="<PATH>\index.json" <TAG>... |
| 337 |
|
| 338 |
The Python install manager can be installed by downloading its installer and |
| 339 |
moving it to another machine before installing. |
| 340 |
|
| 341 |
Alternatively, the ZIP files in an offline index directory can simply be |
| 342 |
transferred to another machine and extracted. This will not register the install |
| 343 |
in any way, and so it must be launched by directly referencing the executables |
| 344 |
in the extracted directory, but it is sometimes a preferable approach in cases |
| 345 |
where installing the Python install manager is not possible or convenient. |
| 346 |
|
| 347 |
In this way, Python runtimes can be installed and managed on a machine without |
| 348 |
access to the internet. |
| 349 |
|
| 350 |
|
| 351 |
Uninstalling runtimes |
| 352 |
--------------------- |
| 353 |
|
| 354 |
.. code:: |
| 355 |
|
| 356 |
$> py uninstall [-y|--yes] <TAG>... |
| 357 |
|
| 358 |
Runtimes may be removed using the ``py uninstall`` command. One or more tags |
| 359 |
must be specified. Ranges are not supported here. |
| 360 |
|
| 361 |
The ``--yes`` option bypasses the confirmation prompt before uninstalling. |
| 362 |
|
| 363 |
Instead of passing tags individually, the ``--purge`` option may be specified. |
| 364 |
This will remove all runtimes managed by the Python install manager, including |
| 365 |
cleaning up the Start menu, registry, and any download caches. Runtimes that |
| 366 |
were not installed by the Python install manager will not be impacted, and |
| 367 |
neither will manually created configuration files. |
| 368 |
|
| 369 |
.. code:: |
| 370 |
|
| 371 |
$> py uninstall [-y|--yes] --purge |
| 372 |
|
| 373 |
The Python install manager can be uninstalled through the Windows "Installed |
| 374 |
apps" settings page. This does not remove any runtimes, and they will still be |
| 375 |
usable, though the global ``python`` and ``py`` commands will be removed. |
| 376 |
Reinstalling the Python install manager will allow you to manage these runtimes |
| 377 |
again. To completely clean up all Python runtimes, run with ``--purge`` before |
| 378 |
uninstalling the Python install manager. |
| 379 |
|
| 380 |
.. _pymanager-config: |
| 381 |
|
| 382 |
Configuration |
| 383 |
------------- |
| 384 |
|
| 385 |
Python install manager is configured with a hierarchy of configuration files, |
| 386 |
environment variables, command-line options, and registry settings. In general, |
| 387 |
configuration files have the ability to configure everything, including the |
| 388 |
location of other configuration files, while registry settings are |
| 389 |
administrator-only and will override configuration files. Command-line options |
| 390 |
override all other settings, but not every option is available. |
| 391 |
|
| 392 |
This section will describe the defaults, but be aware that modified or |
| 393 |
overridden installs may resolve settings differently. |
| 394 |
|
| 395 |
A global configuration file may be configured by an administrator, and would be |
| 396 |
read first. The user configuration file is stored at |
| 397 |
:file:`%AppData%\\Python\\pymanager.json` |
| 398 |
(note that this location is under ``Roaming``, not ``Local``) and is read next, |
| 399 |
overwriting any settings from earlier files. An additional configuration file |
| 400 |
may be specified as the ``PYTHON_MANAGER_CONFIG`` environment variable or the |
| 401 |
``--config`` command line option (but not both). |
| 402 |
These locations may be modified by administrative customization options listed |
| 403 |
later. |
| 404 |
|
| 405 |
The following settings are those that are considered likely to be modified in |
| 406 |
normal use. Later sections list those that are intended for administrative |
| 407 |
customization. |
| 408 |
|
| 409 |
.. Sphinx bug with text writer; remove widths & caption temporarily |
| 410 |
.. :widths: 2, 2, 4 |
| 411 |
|
| 412 |
.. rubric:: Standard configuration options |
| 413 |
|
| 414 |
.. list-table:: |
| 415 |
:header-rows: 1 |
| 416 |
|
| 417 |
* - Config Key |
| 418 |
- Environment Variable |
| 419 |
- Description |
| 420 |
|
| 421 |
* - ``default_tag`` |
| 422 |
- .. envvar:: PYTHON_MANAGER_DEFAULT |
| 423 |
- The preferred default version to launch or install. |
| 424 |
By default, this is interpreted as the most recent non-prerelease version |
| 425 |
from the CPython team. |
| 426 |
|
| 427 |
* - ``default_platform`` |
| 428 |
- ``PYTHON_MANAGER_DEFAULT_PLATFORM`` |
| 429 |
- The preferred default platform to launch or install. |
| 430 |
This is treated as a suffix to the specified tag, such that ``py -V:3.14`` |
| 431 |
would prefer an install for ``3.14-64`` if it exists |
| 432 |
(and ``default_platform`` is ``-64``), |
| 433 |
but will use ``3.14`` if no tagged install exists. |
| 434 |
|
| 435 |
* - ``logs_dir`` |
| 436 |
- ``PYTHON_MANAGER_LOGS`` |
| 437 |
- The location where log files are written. |
| 438 |
By default, :file:`%TEMP%`. |
| 439 |
|
| 440 |
* - ``automatic_install`` |
| 441 |
- .. envvar:: PYTHON_MANAGER_AUTOMATIC_INSTALL |
| 442 |
- True to allow automatic installs when using ``py exec`` to launch (or |
| 443 |
``py`` when no runtimes are installed yet). |
| 444 |
Other commands will not automatically install, regardless of this |
| 445 |
setting. |
| 446 |
By default, true. |
| 447 |
|
| 448 |
* - ``include_unmanaged`` |
| 449 |
- ``PYTHON_MANAGER_INCLUDE_UNMANAGED`` |
| 450 |
- True to allow listing and launching runtimes that were not installed |
| 451 |
by the Python install manager, or false to exclude them. |
| 452 |
By default, true. |
| 453 |
|
| 454 |
* - ``shebang_can_run_anything`` |
| 455 |
- ``PYTHON_MANAGER_SHEBANG_CAN_RUN_ANYTHING`` |
| 456 |
- True to allow shebangs in ``.py`` files to launch applications other than |
| 457 |
Python runtimes, or false to prevent it. |
| 458 |
By default, true. |
| 459 |
|
| 460 |
* - ``log_level`` |
| 461 |
- ``PYMANAGER_VERBOSE``, ``PYMANAGER_DEBUG`` |
| 462 |
- Set the default level of output (0-50). |
| 463 |
By default, 20. |
| 464 |
Lower values produce more output. |
| 465 |
The environment variables are boolean, and may produce additional |
| 466 |
output during startup that is later suppressed by other configuration. |
| 467 |
|
| 468 |
* - ``confirm`` |
| 469 |
- ``PYTHON_MANAGER_CONFIRM`` |
| 470 |
- True to confirm certain actions before taking them (such as uninstall), |
| 471 |
or false to skip the confirmation. |
| 472 |
By default, true. |
| 473 |
|
| 474 |
* - ``install.source`` |
| 475 |
- ``PYTHON_MANAGER_SOURCE_URL`` |
| 476 |
- Override the index feed to obtain new installs from. |
| 477 |
|
| 478 |
* - ``install.enable_entrypoints`` |
| 479 |
- (none) |
| 480 |
- True to generate global commands for installed packages (such as |
| 481 |
``pip.exe``). These are defined by the packages themselves. |
| 482 |
If set to false, only the Python interpreter has global commands created. |
| 483 |
By default, true. You should run ``py install --refresh`` after changing |
| 484 |
this setting. |
| 485 |
|
| 486 |
* - ``list.format`` |
| 487 |
- ``PYTHON_MANAGER_LIST_FORMAT`` |
| 488 |
- Specify the default format used by the ``py list`` command. |
| 489 |
By default, ``table``. |
| 490 |
|
| 491 |
* - ``install_dir`` |
| 492 |
- (none) |
| 493 |
- Specify the root directory that runtimes will be installed into. |
| 494 |
If you change this setting, previously installed runtimes will not be |
| 495 |
usable unless you move them to the new location. |
| 496 |
|
| 497 |
* - ``global_dir`` |
| 498 |
- (none) |
| 499 |
- Specify the directory where global commands (such as ``python3.14.exe`` |
| 500 |
and ``pip.exe``) are stored. |
| 501 |
This directory should be added to your :envvar:`PATH` to make the |
| 502 |
commands available from your terminal. |
| 503 |
|
| 504 |
* - ``download_dir`` |
| 505 |
- (none) |
| 506 |
- Specify the directory where downloaded files are stored. |
| 507 |
This directory is a temporary cache, and can be cleaned up from time to |
| 508 |
time. |
| 509 |
|
| 510 |
|
| 511 |
Dotted names should be nested inside JSON objects, for example, ``list.format`` |
| 512 |
would be specified as ``{"list": {"format": "table"}}``. |
| 513 |
|
| 514 |
.. _pymanager-shebang: |
| 515 |
|
| 516 |
Shebang lines |
| 517 |
------------- |
| 518 |
|
| 519 |
If the first line of a script file starts with ``#!``, it is known as a |
| 520 |
"shebang" line. Linux and other Unix like operating systems have native |
| 521 |
support for such lines and they are commonly used on such systems to indicate |
| 522 |
how a script should be executed. The ``python`` and ``py`` commands allow the |
| 523 |
same facilities to be used with Python scripts on Windows. |
| 524 |
|
| 525 |
To allow shebang lines in Python scripts to be portable between Unix and |
| 526 |
Windows, a number of 'virtual' commands are supported to specify which |
| 527 |
interpreter to use. The supported virtual commands are: |
| 528 |
|
| 529 |
* ``/usr/bin/env <ALIAS>`` |
| 530 |
* ``/usr/bin/env -S <ALIAS>`` |
| 531 |
* ``/usr/bin/<ALIAS>`` |
| 532 |
* ``/usr/local/bin/<ALIAS>`` |
| 533 |
* ``<ALIAS>`` |
| 534 |
|
| 535 |
For example, if the first line of your script starts with |
| 536 |
|
| 537 |
.. code-block:: sh |
| 538 |
|
| 539 |
#! /usr/bin/python |
| 540 |
|
| 541 |
The default Python or an active virtual environment will be located and used. |
| 542 |
As many Python scripts written to work on Unix will already have this line, |
| 543 |
you should find these scripts can be used by the launcher without modification. |
| 544 |
If you are writing a new script on Windows which you hope will be useful on |
| 545 |
Unix, you should use one of the shebang lines starting with ``/usr``. |
| 546 |
|
| 547 |
Any of the above virtual commands can have ``<ALIAS>`` replaced by an alias from |
| 548 |
an installed runtime. That is, any command generated in the global aliases |
| 549 |
directory (which you may have added to your :envvar:`PATH` environment variable) |
| 550 |
can be used in a shebang, even if it is not on your :envvar:`PATH`. This allows |
| 551 |
the use of shebangs like ``/usr/bin/python3.12`` to select a particular runtime. |
| 552 |
|
| 553 |
If no runtimes are installed, or if automatic installation is enabled, the |
| 554 |
requested runtime will be installed if necessary. See :ref:`pymanager-config` |
| 555 |
for information about configuration settings. |
| 556 |
|
| 557 |
The ``/usr/bin/env`` form of shebang line will also search the :envvar:`PATH` |
| 558 |
environment variable for unrecognized commands. This corresponds to the |
| 559 |
behaviour of the Unix ``env`` program, which performs the same search, but |
| 560 |
prefers launching known Python commands. A warning may be displayed when |
| 561 |
searching for arbitrary executables, and this search may be disabled by the |
| 562 |
``shebang_can_run_anything`` configuration option. |
| 563 |
|
| 564 |
Shebang lines that do not match any of patterns are treated as *Windows* |
| 565 |
executable paths that are absolute or relative to the directory containing the |
| 566 |
script file. This is a convenience for Windows-only scripts, such as those |
| 567 |
generated by an installer, since the behavior is not compatible with Unix-style |
| 568 |
shells. These paths may be quoted, and may include multiple arguments, after |
| 569 |
which the path to the script and any additional arguments will be appended. |
| 570 |
This functionality may be disabled by the ``shebang_can_run_anything`` |
| 571 |
configuration option. |
| 572 |
|
| 573 |
.. note:: |
| 574 |
|
| 575 |
The behaviour of shebangs in the Python install manager is subtly different |
| 576 |
from the previous ``py.exe`` launcher, and the old configuration options no |
| 577 |
longer apply. If you are specifically reliant on the old behaviour or |
| 578 |
configuration, we recommend installing the `legacy launcher`_. The legacy |
| 579 |
launcher's ``py`` command will override PyManager's one by default, and you |
| 580 |
will need to use ``pymanager`` commands for installing and uninstalling. |
| 581 |
|
| 582 |
.. _Add-AppxPackage: https://learn.microsoft.com/powershell/module/appx/add-appxpackage |
| 583 |
|
| 584 |
.. _Remove-AppxPackage: https://learn.microsoft.com/powershell/module/appx/remove-appxpackage |
| 585 |
|
| 586 |
.. _Add-AppxProvisionedPackage: https://learn.microsoft.com/powershell/module/dism/add-appxprovisionedpackage |
| 587 |
|
| 588 |
.. _PackageManager: https://learn.microsoft.com/uwp/api/windows.management.deployment.packagemanager |
| 589 |
|
| 590 |
.. _pymanager-advancedinstall: |
| 591 |
|
| 592 |
Advanced installation |
| 593 |
--------------------- |
| 594 |
|
| 595 |
For situations where an MSIX cannot be installed, such as some older |
| 596 |
administrative distribution platforms, there is an MSI available from the |
| 597 |
python.org downloads page. This MSI has no user interface, and can only perform |
| 598 |
per-machine installs to its default location in Program Files. It will attempt |
| 599 |
to modify the system :envvar:`PATH` environment variable to include this install |
| 600 |
location, but be sure to validate this on your configuration. |
| 601 |
|
| 602 |
.. note:: |
| 603 |
|
| 604 |
Windows Server 2019 is the only version of Windows that CPython supports that |
| 605 |
does not support MSIX. For Windows Server 2019, you should use the MSI. |
| 606 |
|
| 607 |
Be aware that the MSI package does not bundle any runtimes, and so is not |
| 608 |
suitable for installs into offline environments without also creating an offline |
| 609 |
install index. See :ref:`pymanager-offline` and :ref:`pymanager-admin-config` |
| 610 |
for information on handling these scenarios. |
| 611 |
|
| 612 |
Runtimes installed by the MSI are shared with those installed by the MSIX, and |
| 613 |
are all per-user only. The Python install manager does not support installing |
| 614 |
runtimes per-machine. To emulate a per-machine install, you can use ``py install |
| 615 |
--target=<shared location>`` as administrator and add your own system-wide |
| 616 |
modifications to :envvar:`PATH`, the registry, or the Start menu. |
| 617 |
|
| 618 |
When the MSIX is installed, but commands are not available in the :envvar:`PATH` |
| 619 |
environment variable, they can be found under |
| 620 |
:file:`%LocalAppData%\\Microsoft\\WindowsApps\\PythonSoftwareFoundation.PythonManager_3847v3x7pw1km` |
| 621 |
or |
| 622 |
:file:`%LocalAppData%\\Microsoft\\WindowsApps\\PythonSoftwareFoundation.PythonManager_qbz5n2kfra8p0`, |
| 623 |
depending on whether it was installed from python.org or through the Windows |
| 624 |
Store. Attempting to run the executable directly from Program Files is not |
| 625 |
recommended. |
| 626 |
|
| 627 |
To programmatically install the Python install manager, it is easiest to use |
| 628 |
WinGet, which is included with all supported versions of Windows: |
| 629 |
|
| 630 |
.. code-block:: powershell |
| 631 |
|
| 632 |
$> winget install 9NQ7512CXL7T -e --accept-package-agreements --disable-interactivity |
| 633 |
|
| 634 |
# Optionally run the configuration checker and accept all changes |
| 635 |
$> py install --configure -y |
| 636 |
|
| 637 |
To download the Python install manager and install on another machine, the |
| 638 |
following WinGet command will download the required files from the Store to your |
| 639 |
Downloads directory (add ``-d <location>`` to customize the output location). |
| 640 |
This also generates a YAML file that appears to be unnecessary, as the |
| 641 |
downloaded MSIX can be installed by launching or using the commands below. |
| 642 |
|
| 643 |
.. code-block:: powershell |
| 644 |
|
| 645 |
$> winget download 9NQ7512CXL7T -e --skip-license --accept-package-agreements --accept-source-agreements |
| 646 |
|
| 647 |
To programmatically install or uninstall an MSIX using only PowerShell, the |
| 648 |
`Add-AppxPackage`_ and `Remove-AppxPackage`_ PowerShell cmdlets are recommended: |
| 649 |
|
| 650 |
.. code-block:: powershell |
| 651 |
|
| 652 |
$> Add-AppxPackage C:\Downloads\python-manager-25.0.msix |
| 653 |
... |
| 654 |
$> Get-AppxPackage PythonSoftwareFoundation.PythonManager | Remove-AppxPackage |
| 655 |
|
| 656 |
The latest release can be downloaded and installed by Windows by passing the |
| 657 |
AppInstaller file to the Add-AppxPackage command. This installs using the MSIX |
| 658 |
on python.org, and is only recommended for cases where installing via the Store |
| 659 |
(interactively or using WinGet) is not possible. |
| 660 |
|
| 661 |
.. code-block:: powershell |
| 662 |
|
| 663 |
$> Add-AppxPackage -AppInstallerFile https://www.python.org/ftp/python/pymanager/pymanager.appinstaller |
| 664 |
|
| 665 |
Other tools and APIs may also be used to provision an MSIX package for all users |
| 666 |
on a machine, but Python does not consider this a supported scenario. We suggest |
| 667 |
looking into the PowerShell `Add-AppxProvisionedPackage`_ cmdlet, the native |
| 668 |
Windows `PackageManager`_ class, or the documentation and support for your |
| 669 |
deployment tool. |
| 670 |
|
| 671 |
Regardless of the install method, users will still need to install their own |
| 672 |
copies of Python itself, as there is no way to trigger those installs without |
| 673 |
being a logged in user. When using the MSIX, the latest version of Python will |
| 674 |
be available for all users to install without network access. |
| 675 |
|
| 676 |
Note that the MSIX downloadable from the Store and from the Python website are |
| 677 |
subtly different and cannot be installed at the same time. Wherever possible, |
| 678 |
we suggest using the above WinGet commands to download the package from the |
| 679 |
Store to reduce the risk of setting up conflicting installs. There are no |
| 680 |
licensing restrictions on the Python install manager that would prevent using |
| 681 |
the Store package in this way. |
| 682 |
|
| 683 |
|
| 684 |
.. _pymanager-admin-config: |
| 685 |
|
| 686 |
Administrative configuration |
| 687 |
---------------------------- |
| 688 |
|
| 689 |
There are a number of options that may be useful for administrators to override |
| 690 |
configuration of the Python install manager. These can be used to provide local |
| 691 |
caching, disable certain shortcut types, override bundled content. All of the |
| 692 |
above configuration options may be set, as well as those below. |
| 693 |
|
| 694 |
Configuration options may be overridden in the registry by setting values under |
| 695 |
:file:`HKEY_LOCAL_MACHINE\\Software\\Policies\\Python\\PyManager`, where the |
| 696 |
value name matches the configuration key and the value type is ``REG_SZ``. Note |
| 697 |
that this key can itself be customized, but only by modifying the core config |
| 698 |
file distributed with the Python install manager. We recommend, however, that |
| 699 |
registry values are used only to set ``base_config`` to a JSON file containing |
| 700 |
the full set of overrides. Registry key overrides will replace any other |
| 701 |
configured setting, while ``base_config`` allows users to further modify |
| 702 |
settings they may need. |
| 703 |
|
| 704 |
Note that most settings with environment variables support those variables |
| 705 |
because their default setting specifies the variable. If you override them, the |
| 706 |
environment variable will no longer work, unless you override it with another |
| 707 |
one. For example, the default value of ``confirm`` is literally |
| 708 |
``%PYTHON_MANAGER_CONFIRM%``, which will resolve the variable at load time. If |
| 709 |
you override the value to ``yes``, then the environment variable will no longer |
| 710 |
be used. If you override the value to ``%CONFIRM%``, then that environment |
| 711 |
variable will be used instead. |
| 712 |
|
| 713 |
Configuration settings that are paths are interpreted as relative to the |
| 714 |
directory containing the configuration file that specified them. |
| 715 |
|
| 716 |
.. Sphinx bug with text writer; remove widths & caption temporarily |
| 717 |
.. :widths: 1, 4 |
| 718 |
|
| 719 |
.. rubric:: Administrative configuration options |
| 720 |
|
| 721 |
.. list-table:: |
| 722 |
:header-rows: 1 |
| 723 |
|
| 724 |
* - Config Key |
| 725 |
- Description |
| 726 |
|
| 727 |
* - ``base_config`` |
| 728 |
- The highest priority configuration file to read. |
| 729 |
Note that only the built-in configuration file and the registry can |
| 730 |
modify this setting. |
| 731 |
|
| 732 |
* - ``user_config`` |
| 733 |
- The second configuration file to read. |
| 734 |
|
| 735 |
* - ``additional_config`` |
| 736 |
- The third configuration file to read. |
| 737 |
|
| 738 |
* - ``registry_override_key`` |
| 739 |
- Registry location to check for overrides. |
| 740 |
Note that only the built-in configuration file can modify this setting. |
| 741 |
|
| 742 |
* - ``bundled_dir`` |
| 743 |
- Read-only directory containing locally cached files. |
| 744 |
|
| 745 |
* - ``install.fallback_source`` |
| 746 |
- Path or URL to an index to consult when the main index cannot be accessed. |
| 747 |
|
| 748 |
* - ``install.enable_shortcut_kinds`` |
| 749 |
- Comma-separated list of shortcut kinds to allow (e.g. ``"pep514,start"``). |
| 750 |
Enabled shortcuts may still be disabled by ``disable_shortcut_kinds``. |
| 751 |
|
| 752 |
* - ``install.disable_shortcut_kinds`` |
| 753 |
- Comma-separated list of shortcut kinds to exclude |
| 754 |
(e.g. ``"pep514,start"``). |
| 755 |
Disabled shortcuts are not reactivated by ``enable_shortcut_kinds``. |
| 756 |
|
| 757 |
* - ``install.hard_link_entrypoints`` |
| 758 |
- True to use hard links for global shortcuts to save disk space. If false, |
| 759 |
each shortcut executable is copied instead. After changing this setting, |
| 760 |
you must run ``py install --refresh --force`` to update existing |
| 761 |
commands. |
| 762 |
By default, true. Disabling this may be necessary for troubleshooting or |
| 763 |
systems that have issues with file links. |
| 764 |
|
| 765 |
* - ``pep514_root`` |
| 766 |
- Registry location to read and write PEP 514 entries into. |
| 767 |
By default, :file:`HKEY_CURRENT_USER\\Software\\Python`. |
| 768 |
|
| 769 |
* - ``start_folder`` |
| 770 |
- Start menu folder to write shortcuts into. |
| 771 |
By default, ``Python``. |
| 772 |
This path is relative to the user's Programs folder. |
| 773 |
|
| 774 |
* - ``virtual_env`` |
| 775 |
- Path to the active virtual environment. |
| 776 |
By default, this is ``%VIRTUAL_ENV%``, but may be set empty |
| 777 |
to disable venv detection. |
| 778 |
|
| 779 |
* - ``shebang_can_run_anything_silently`` |
| 780 |
- True to suppress visible warnings when a shebang launches an application |
| 781 |
other than a Python runtime. |
| 782 |
|
| 783 |
* - ``source_settings`` |
| 784 |
- A mapping from source URL to settings specific to that index. |
| 785 |
When multiple configuration files include this section, URL settings are |
| 786 |
added or overwritten, but individual settings are not merged. |
| 787 |
These settings are currently only for :ref:`index signatures |
| 788 |
<pymanager-index-signatures>`. |
| 789 |
|
| 790 |
|
| 791 |
.. _install-freethreaded-windows: |
| 792 |
|
| 793 |
Installing free-threaded binaries |
| 794 |
--------------------------------- |
| 795 |
|
| 796 |
.. versionadded:: 3.13 |
| 797 |
|
| 798 |
Pre-built distributions of the free-threaded build are available |
| 799 |
by installing tags with the ``t`` suffix. |
| 800 |
|
| 801 |
.. code:: |
| 802 |
|
| 803 |
$> py install 3.14t |
| 804 |
$> py install 3.14t-arm64 |
| 805 |
$> py install 3.14t-32 |
| 806 |
|
| 807 |
This will install and register as normal. If you have no other runtimes |
| 808 |
installed, then ``python`` will launch this one. Otherwise, you will need to use |
| 809 |
``py -V:3.14t ...`` or, if you have added the global aliases directory to your |
| 810 |
:envvar:`PATH` environment variable, the ``python3.14t.exe`` commands. |
| 811 |
|
| 812 |
|
| 813 |
.. _pymanager-index-signatures: |
| 814 |
|
| 815 |
Index signatures |
| 816 |
---------------- |
| 817 |
|
| 818 |
.. versionadded:: 26.2 |
| 819 |
|
| 820 |
Index files may be signed to detect tampering. A signature is a catalog file |
| 821 |
at the same URL as the index with ``.cat`` added to the filename. The catalog |
| 822 |
file should contain the hash of its matching index file, and should be signed |
| 823 |
with a valid Authenticode signature. This allows standard tooling (on Windows) |
| 824 |
to generate a signature, and any certificate may be used as long as the client |
| 825 |
operating system already trusts its certification authority (root CA). |
| 826 |
|
| 827 |
Index signatures are only downloaded and checked when the local configuration's |
| 828 |
``source_settings`` section includes the index URL and ``requires_signature`` is |
| 829 |
true, or the index JSON contains ``requires_signature`` set to true. When the |
| 830 |
setting exists in local configuration, even when false, settings in the index |
| 831 |
are ignored. |
| 832 |
|
| 833 |
As well as requiring a valid signature, the ``required_root_subject`` and |
| 834 |
``required_publisher_subject`` settings can further restrict acceptable |
| 835 |
signatures based on the certificate Subject fields. Any attribute specified in |
| 836 |
the configuration must match the attribute in the certificate (additional |
| 837 |
attributes in the certificate are ignored). Typical attributes are ``CN=`` for |
| 838 |
the common name, ``O=`` for the organizational unit, and ``C=`` for the |
| 839 |
publisher's country. |
| 840 |
|
| 841 |
Finally, the ``required_publisher_eku`` setting allows requiring that a specific |
| 842 |
Enhanced Key Usage (EKU) has been assigned to the publisher certificate. For |
| 843 |
example, the EKU ``1.3.6.1.5.5.7.3.3`` indicates that the certificate was |
| 844 |
intended for code signing (as opposed to server or client authentication). |
| 845 |
In combination with a specific root CA, this provides another mechanism to |
| 846 |
verify a legitimate signature. |
| 847 |
|
| 848 |
This is an example ``source_settings`` section from a configuration file. In |
| 849 |
this case, the publisher of the feed is uniquely identified by the combination |
| 850 |
of the Microsoft Identity Verification root and the EKU assigned by that root. |
| 851 |
The signature for this case would be found at |
| 852 |
``https://www.python.org/ftp/python/index-windows.json.cat``. |
| 853 |
|
| 854 |
.. code:: json5 |
| 855 |
|
| 856 |
{ |
| 857 |
"source_settings": { |
| 858 |
"https://www.python.org/ftp/python/index-windows.json": { |
| 859 |
"requires_signature": true, |
| 860 |
"required_root_subject": "CN=Microsoft Identity Verification Root Certificate Authority 2020", |
| 861 |
"required_publisher_subject": "CN=Python Software Foundation", |
| 862 |
"required_publisher_eku": "1.3.6.1.4.1.311.97.608394634.79987812.305991749.578777327" |
| 863 |
} |
| 864 |
} |
| 865 |
} |
| 866 |
|
| 867 |
The same settings could be specified in the ``index.json`` file instead. In this |
| 868 |
case, the root and EKU are omitted, meaning that the signature must be valid and |
| 869 |
have a specific common name in the publisher's certificate, but no other checks |
| 870 |
are used. |
| 871 |
|
| 872 |
.. code:: json5 |
| 873 |
|
| 874 |
{ |
| 875 |
"requires_signature": true, |
| 876 |
"required_publisher_subject": "CN=Python Software Foundation", |
| 877 |
"versions": [ |
| 878 |
// ... |
| 879 |
] |
| 880 |
} |
| 881 |
|
| 882 |
When settings from inside a feed are used, the user is notified and the settings |
| 883 |
are shown in the log file or verbose output. It is recommended to copy these |
| 884 |
settings into a local configuration file for feeds that will be used frequently, |
| 885 |
so that unauthorised modifications to the feed cannot disable verification. |
| 886 |
|
| 887 |
It is not possible to override the location of the signature file in the feed or |
| 888 |
through a configuration file. Administrators can provide their own |
| 889 |
``source_settings`` in a mandatory configuration file (see |
| 890 |
:ref:`pymanager-admin-config`). |
| 891 |
|
| 892 |
If signature validation fails, you will be notified and prompted to continue. |
| 893 |
When interactive confirmation is not allowed (for example, because ``--yes`` was |
| 894 |
specified), it will always abort. To use a feed with invalid configuration in |
| 895 |
this scenario, you must provide a configuration file that disables signature |
| 896 |
checking for that feed. |
| 897 |
|
| 898 |
.. code:: json5 |
| 899 |
|
| 900 |
"source_settings": { |
| 901 |
"https://www.example.com/feed-with-invalid-signature.json": { |
| 902 |
"requires_signature": false |
| 903 |
} |
| 904 |
} |
| 905 |
|
| 906 |
|
| 907 |
.. _pymanager-troubleshoot: |
| 908 |
|
| 909 |
Troubleshooting |
| 910 |
--------------- |
| 911 |
|
| 912 |
If your Python install manager does not seem to be working correctly, please |
| 913 |
work through these tests and fixes to see if it helps. If not, please report an |
| 914 |
issue at `our bug tracker <https://github.com/python/pymanager/issues>`_, |
| 915 |
including any relevant log files (written to your :file:`%TEMP%` directory by |
| 916 |
default). |
| 917 |
|
| 918 |
.. Sphinx bug with text writer; remove widths & caption temporarily |
| 919 |
.. :widths: 1, 1 |
| 920 |
|
| 921 |
.. rubric:: Troubleshooting |
| 922 |
|
| 923 |
.. list-table:: |
| 924 |
:header-rows: 1 |
| 925 |
|
| 926 |
* - Symptom |
| 927 |
- Things to try |
| 928 |
|
| 929 |
* - ``python`` gives me a "command not found" error or opens the Store app |
| 930 |
when I type it in my terminal. |
| 931 |
- Did you :ref:`install the Python install manager <pymanager>`? |
| 932 |
|
| 933 |
* - |
| 934 |
- Click Start, open "Manage app execution aliases", and check that the |
| 935 |
aliases for "Python (default)" are enabled. |
| 936 |
If they already are, try disabling and re-enabling to refresh the command. |
| 937 |
The "Python (default windowed)" and "Python install manager" commands |
| 938 |
may also need refreshing. |
| 939 |
|
| 940 |
* - |
| 941 |
- Check that the ``py`` and ``pymanager`` commands work. |
| 942 |
|
| 943 |
* - |
| 944 |
- Ensure your :envvar:`PATH` variable contains the entry for |
| 945 |
``%UserProfile%\AppData\Local\Microsoft\WindowsApps``. |
| 946 |
The operating system includes this entry once by default, after other |
| 947 |
user paths. If removed, shortcuts will not be found. |
| 948 |
|
| 949 |
* - ``py`` gives me a "command not found" error when I type it in my terminal. |
| 950 |
- Did you :ref:`install the Python install manager <pymanager>`? |
| 951 |
|
| 952 |
* - |
| 953 |
- Click Start, open "Manage app execution aliases", and check that the |
| 954 |
aliases for "Python (default)" are enabled. |
| 955 |
If they already are, try disabling and re-enabling to refresh the command. |
| 956 |
The "Python (default windowed)" and "Python install manager" commands |
| 957 |
may also need refreshing. |
| 958 |
|
| 959 |
* - |
| 960 |
- Ensure your :envvar:`PATH` variable contains the entry for |
| 961 |
``%UserProfile%\AppData\Local\Microsoft\WindowsApps``. |
| 962 |
The operating system includes this entry once by default, after other |
| 963 |
user paths. If removed, shortcuts will not be found. |
| 964 |
|
| 965 |
* - ``py`` gives me a "can't open file" error when I type commands in my |
| 966 |
terminal. |
| 967 |
- This usually means you have the legacy launcher installed and |
| 968 |
it has priority over the Python install manager. |
| 969 |
To remove, click Start, open "Installed apps", |
| 970 |
search for "Python launcher" and uninstall it. |
| 971 |
|
| 972 |
* - ``python`` doesn't launch the same runtime as ``py`` |
| 973 |
- Click Start, open "Installed apps", look for any existing Python runtimes, |
| 974 |
and either remove them or Modify and disable the :envvar:`PATH` options. |
| 975 |
|
| 976 |
* - |
| 977 |
- Click Start, open "Manage app execution aliases", and check that your |
| 978 |
``python.exe`` alias is set to "Python (default)" |
| 979 |
|
| 980 |
* - ``python`` and ``py`` don't launch the runtime I expect |
| 981 |
- Check your :envvar:`PYTHON_MANAGER_DEFAULT` environment variable |
| 982 |
or ``default_tag`` configuration. |
| 983 |
The ``py list`` command will show your default based on these settings. |
| 984 |
|
| 985 |
* - |
| 986 |
- Installs that are managed by the Python install manager will be chosen |
| 987 |
ahead of unmanaged installs. |
| 988 |
Use ``py install`` to install the runtime you expect, |
| 989 |
or configure your default tag. |
| 990 |
|
| 991 |
* - |
| 992 |
- Prerelease and experimental installs that are not managed by the Python |
| 993 |
install manager may be chosen ahead of stable releases. |
| 994 |
Configure your default tag or uninstall the prerelease runtime |
| 995 |
and reinstall it using ``py install``. |
| 996 |
|
| 997 |
* - ``pythonw`` or ``pyw`` don't launch the same runtime as ``python`` or ``py`` |
| 998 |
- Click Start, open "Manage app execution aliases", and check that your |
| 999 |
``pythonw.exe`` and ``pyw.exe`` aliases are consistent with your others. |
| 1000 |
|
| 1001 |
* - ``pip`` gives me a "command not found" error when I type it in my terminal. |
| 1002 |
- Have you activated a virtual environment? |
| 1003 |
Run the ``.venv\Scripts\activate`` script in your terminal to activate. |
| 1004 |
|
| 1005 |
* - |
| 1006 |
- The package may be available but missing the generated executable. |
| 1007 |
We recommend using the ``python -m pip`` command instead. |
| 1008 |
Running ``py install --refresh`` and ensuring that the global shortcuts |
| 1009 |
directory is on :envvar:`PATH` (it will be shown in the command output if |
| 1010 |
it is not) should make commands such as ``pip`` (and other installed |
| 1011 |
packages) available. |
| 1012 |
|
| 1013 |
* - I installed a package with ``pip`` but its command is not found. |
| 1014 |
- Have you activated a virtual environment? |
| 1015 |
Run the ``.venv\Scripts\activate`` script in your terminal to activate. |
| 1016 |
|
| 1017 |
* - |
| 1018 |
- New packages do not automatically have global shortcuts created by the |
| 1019 |
Python install manager. Similarly, uninstalled packages do not have their |
| 1020 |
shortcuts removed. |
| 1021 |
Run ``py install --refresh`` to update the global shortcuts for newly |
| 1022 |
installed packages. |
| 1023 |
|
| 1024 |
* - Typing ``script-name.py`` in the terminal opens in a new window. |
| 1025 |
- This is a known limitation of the operating system. Either specify ``py`` |
| 1026 |
before the script name, create a batch file containing ``@py "%~dpn0.py" %*`` |
| 1027 |
with the same name as the script, or install the `legacy launcher`_ |
| 1028 |
and select it as the association for scripts. |
| 1029 |
|
| 1030 |
* - Drag-dropping files onto a script doesn't work |
| 1031 |
- This is a known limitation of the operating system. It is supported with |
| 1032 |
the `legacy launcher`_, or with the Python install manager when installed |
| 1033 |
from the MSI. |
| 1034 |
|
| 1035 |
* - I have installed the Python install manager multiple times. |
| 1036 |
- It is possible to install from the Store or WinGet, from the MSIX on |
| 1037 |
the Python website, and from the MSI, all at once. |
| 1038 |
They are all compatible and will share configuration and runtimes. |
| 1039 |
|
| 1040 |
* - |
| 1041 |
- See the earlier :ref:`pymanager-advancedinstall` section for ways to |
| 1042 |
uninstall the install manager other than the typical Installed Apps |
| 1043 |
(Add and Remove Programs) settings page. |
| 1044 |
|
| 1045 |
* - My old ``py.ini`` settings no longer work. |
| 1046 |
- The new Python install manager no longer supports this configuration file |
| 1047 |
or its settings, and so it will be ignored. |
| 1048 |
See :ref:`pymanager-config` for information about configuration settings. |
| 1049 |
|
| 1050 |
.. _windows-embeddable: |
| 1051 |
|
| 1052 |
The embeddable package |
| 1053 |
====================== |
| 1054 |
|
| 1055 |
.. versionadded:: 3.5 |
| 1056 |
|
| 1057 |
The embedded distribution is a ZIP file containing a minimal Python environment. |
| 1058 |
It is intended for acting as part of another application, rather than being |
| 1059 |
directly accessed by end-users. |
| 1060 |
|
| 1061 |
To install an embedded distribution, we recommend using ``py install`` with the |
| 1062 |
``--target`` option: |
| 1063 |
|
| 1064 |
.. code:: |
| 1065 |
|
| 1066 |
$> py install 3.14-embed --target=<directory> |
| 1067 |
|
| 1068 |
When extracted, the embedded distribution is (almost) fully isolated from the |
| 1069 |
user's system, including environment variables, system registry settings, and |
| 1070 |
installed packages. The standard library is included as pre-compiled and |
| 1071 |
optimized ``.pyc`` files in a ZIP, and ``python3.dll``, ``python313.dll``, |
| 1072 |
``python.exe`` and ``pythonw.exe`` are all provided. Tcl/tk (including all |
| 1073 |
dependents, such as Idle), pip and the Python documentation are not included. |
| 1074 |
|
| 1075 |
A default ``._pth`` file is included, which further restricts the default search |
| 1076 |
paths (as described below in :ref:`windows_finding_modules`). This file is |
| 1077 |
intended for embedders to modify as necessary. |
| 1078 |
|
| 1079 |
Third-party packages should be installed by the application installer alongside |
| 1080 |
the embedded distribution. Using pip to manage dependencies as for a regular |
| 1081 |
Python installation is not supported with this distribution, though with some |
| 1082 |
care it may be possible to include and use pip for automatic updates. In |
| 1083 |
general, third-party packages should be treated as part of the application |
| 1084 |
("vendoring") so that the developer can ensure compatibility with newer |
| 1085 |
versions before providing updates to users. |
| 1086 |
|
| 1087 |
The two recommended use cases for this distribution are described below. |
| 1088 |
|
| 1089 |
Python application |
| 1090 |
------------------ |
| 1091 |
|
| 1092 |
An application written in Python does not necessarily require users to be aware |
| 1093 |
of that fact. The embedded distribution may be used in this case to include a |
| 1094 |
private version of Python in an install package. Depending on how transparent it |
| 1095 |
should be (or conversely, how professional it should appear), there are two |
| 1096 |
options. |
| 1097 |
|
| 1098 |
Using a specialized executable as a launcher requires some coding, but provides |
| 1099 |
the most transparent experience for users. With a customized launcher, there are |
| 1100 |
no obvious indications that the program is running on Python: icons can be |
| 1101 |
customized, company and version information can be specified, and file |
| 1102 |
associations behave properly. In most cases, a custom launcher should simply be |
| 1103 |
able to call ``Py_Main`` with a hard-coded command line. |
| 1104 |
|
| 1105 |
The simpler approach is to provide a batch file or generated shortcut that |
| 1106 |
directly calls the ``python.exe`` or ``pythonw.exe`` with the required |
| 1107 |
command-line arguments. In this case, the application will appear to be Python |
| 1108 |
and not its actual name, and users may have trouble distinguishing it from other |
| 1109 |
running Python processes or file associations. |
| 1110 |
|
| 1111 |
With the latter approach, packages should be installed as directories alongside |
| 1112 |
the Python executable to ensure they are available on the path. With the |
| 1113 |
specialized launcher, packages can be located in other locations as there is an |
| 1114 |
opportunity to specify the search path before launching the application. |
| 1115 |
|
| 1116 |
Embedding Python |
| 1117 |
---------------- |
| 1118 |
|
| 1119 |
Applications written in native code often require some form of scripting |
| 1120 |
language, and the embedded Python distribution can be used for this purpose. In |
| 1121 |
general, the majority of the application is in native code, and some part will |
| 1122 |
either invoke ``python.exe`` or directly use ``python3.dll``. For either case, |
| 1123 |
extracting the embedded distribution to a subdirectory of the application |
| 1124 |
installation is sufficient to provide a loadable Python interpreter. |
| 1125 |
|
| 1126 |
As with the application use, packages can be installed to any location as there |
| 1127 |
is an opportunity to specify search paths before initializing the interpreter. |
| 1128 |
Otherwise, there is no fundamental differences between using the embedded |
| 1129 |
distribution and a regular installation. |
| 1130 |
|
| 1131 |
|
| 1132 |
.. _windows-nuget: |
| 1133 |
|
| 1134 |
The nuget.org packages |
| 1135 |
====================== |
| 1136 |
|
| 1137 |
.. versionadded:: 3.5.2 |
| 1138 |
|
| 1139 |
The nuget.org package is a reduced size Python environment intended for use on |
| 1140 |
continuous integration and build systems that do not have a system-wide |
| 1141 |
install of Python. While nuget is "the package manager for .NET", it also works |
| 1142 |
perfectly fine for packages containing build-time tools. |
| 1143 |
|
| 1144 |
Visit `nuget.org <https://www.nuget.org/>`_ for the most up-to-date information |
| 1145 |
on using nuget. What follows is a summary that is sufficient for Python |
| 1146 |
developers. |
| 1147 |
|
| 1148 |
The ``nuget.exe`` command line tool may be downloaded directly from |
| 1149 |
``https://aka.ms/nugetclidl``, for example, using curl or PowerShell. With the |
| 1150 |
tool, the latest version of Python for 64-bit or 32-bit machines is installed |
| 1151 |
using:: |
| 1152 |
|
| 1153 |
nuget.exe install python -ExcludeVersion -OutputDirectory . |
| 1154 |
nuget.exe install pythonx86 -ExcludeVersion -OutputDirectory . |
| 1155 |
|
| 1156 |
To select a particular version, add a ``-Version 3.x.y``. The output directory |
| 1157 |
may be changed from ``.``, and the package will be installed into a |
| 1158 |
subdirectory. By default, the subdirectory is named the same as the package, |
| 1159 |
and without the ``-ExcludeVersion`` option this name will include the specific |
| 1160 |
version installed. Inside the subdirectory is a ``tools`` directory that |
| 1161 |
contains the Python installation: |
| 1162 |
|
| 1163 |
.. code-block:: doscon |
| 1164 |
|
| 1165 |
# Without -ExcludeVersion |
| 1166 |
> .\python.3.5.2\tools\python.exe -V |
| 1167 |
Python 3.5.2 |
| 1168 |
|
| 1169 |
# With -ExcludeVersion |
| 1170 |
> .\python\tools\python.exe -V |
| 1171 |
Python 3.5.2 |
| 1172 |
|
| 1173 |
In general, nuget packages are not upgradeable, and newer versions should be |
| 1174 |
installed side-by-side and referenced using the full path. Alternatively, |
| 1175 |
delete the package directory manually and install it again. Many CI systems |
| 1176 |
will do this automatically if they do not preserve files between builds. |
| 1177 |
|
| 1178 |
Alongside the ``tools`` directory is a ``build\native`` directory. This |
| 1179 |
contains a MSBuild properties file ``python.props`` that can be used in a |
| 1180 |
C++ project to reference the Python install. Including the settings will |
| 1181 |
automatically use the headers and import libraries in your build. |
| 1182 |
|
| 1183 |
The package information pages on nuget.org are |
| 1184 |
`www.nuget.org/packages/python <https://www.nuget.org/packages/python>`_ |
| 1185 |
for the 64-bit version, `www.nuget.org/packages/pythonx86 |
| 1186 |
<https://www.nuget.org/packages/pythonx86>`_ for the 32-bit version, and |
| 1187 |
`www.nuget.org/packages/pythonarm64 |
| 1188 |
<https://www.nuget.org/packages/pythonarm64>`_ for the ARM64 version |
| 1189 |
|
| 1190 |
Free-threaded packages |
| 1191 |
---------------------- |
| 1192 |
|
| 1193 |
.. versionadded:: 3.13 |
| 1194 |
|
| 1195 |
Packages containing free-threaded binaries are named |
| 1196 |
`python-freethreaded <https://www.nuget.org/packages/python-freethreaded>`_ |
| 1197 |
for the 64-bit version, `pythonx86-freethreaded |
| 1198 |
<https://www.nuget.org/packages/pythonx86-freethreaded>`_ for the 32-bit |
| 1199 |
version, and `pythonarm64-freethreaded |
| 1200 |
<https://www.nuget.org/packages/pythonarm64-freethreaded>`_ for the ARM64 |
| 1201 |
version. These packages contain both the ``python3.13t.exe`` and |
| 1202 |
``python.exe`` entry points, both of which run free threaded. |
| 1203 |
|
| 1204 |
|
| 1205 |
Alternative bundles |
| 1206 |
=================== |
| 1207 |
|
| 1208 |
Besides the standard CPython distribution, there are modified packages including |
| 1209 |
additional functionality. The following is a list of popular versions and their |
| 1210 |
key features: |
| 1211 |
|
| 1212 |
`ActivePython <https://www.activestate.com/products/python/>`_ |
| 1213 |
Installer with multi-platform compatibility, documentation, PyWin32 |
| 1214 |
|
| 1215 |
`Anaconda <https://www.anaconda.com/download/>`_ |
| 1216 |
Popular scientific modules (such as numpy, scipy and pandas) and the |
| 1217 |
``conda`` package manager. |
| 1218 |
|
| 1219 |
`Enthought Deployment Manager <https://assets.enthought.com/downloads/edm/>`_ |
| 1220 |
"The Next Generation Python Environment and Package Manager". |
| 1221 |
|
| 1222 |
Previously Enthought provided Canopy, but it `reached end of life in 2016 |
| 1223 |
<https://support.enthought.com/hc/en-us/articles/360038600051-Canopy-GUI-end-of-life-transition-to-the-Enthought-Deployment-Manager-EDM-and-Visual-Studio-Code>`_. |
| 1224 |
|
| 1225 |
`WinPython <https://winpython.github.io/>`_ |
| 1226 |
Windows-specific distribution with prebuilt scientific packages and |
| 1227 |
tools for building packages. |
| 1228 |
|
| 1229 |
Note that these packages may not include the latest versions of Python or |
| 1230 |
other libraries, and are not maintained or supported by the core Python team. |
| 1231 |
|
| 1232 |
|
| 1233 |
Supported Windows versions |
| 1234 |
========================== |
| 1235 |
|
| 1236 |
As specified in :pep:`11`, a Python release only supports a Windows platform |
| 1237 |
while Microsoft considers the platform under extended support. This means that |
| 1238 |
Python |version| supports Windows 10 and newer. If you require Windows 7 |
| 1239 |
support, please install Python 3.8. If you require Windows 8.1 support, |
| 1240 |
please install Python 3.12. |
| 1241 |
|
| 1242 |
|
| 1243 |
.. _max-path: |
| 1244 |
|
| 1245 |
Removing the MAX_PATH limitation |
| 1246 |
================================ |
| 1247 |
|
| 1248 |
Windows historically has limited path lengths to 260 characters. This meant that |
| 1249 |
paths longer than this would not resolve and errors would result. |
| 1250 |
|
| 1251 |
In the latest versions of Windows, this limitation can be expanded to over |
| 1252 |
32,000 characters. Your administrator will need to activate the "Enable Win32 |
| 1253 |
long paths" group policy, or set ``LongPathsEnabled`` to ``1`` in the registry |
| 1254 |
key ``HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem``. |
| 1255 |
|
| 1256 |
This allows the :func:`open` function, the :mod:`os` module and most other |
| 1257 |
path functionality to accept and return paths longer than 260 characters. |
| 1258 |
|
| 1259 |
After changing the above option and rebooting, no further configuration is |
| 1260 |
required. |
| 1261 |
|
| 1262 |
|
| 1263 |
.. _win-utf8-mode: |
| 1264 |
|
| 1265 |
UTF-8 mode |
| 1266 |
========== |
| 1267 |
|
| 1268 |
.. versionadded:: 3.7 |
| 1269 |
|
| 1270 |
Windows still uses legacy encodings for the system encoding (the ANSI Code |
| 1271 |
Page). Python uses it for the default encoding of text files (e.g. |
| 1272 |
:func:`locale.getencoding`). |
| 1273 |
|
| 1274 |
This may cause issues because UTF-8 is widely used on the internet |
| 1275 |
and most Unix systems, including WSL (Windows Subsystem for Linux). |
| 1276 |
|
| 1277 |
You can use the :ref:`Python UTF-8 Mode <utf8-mode>` to change the default text |
| 1278 |
encoding to UTF-8. You can enable the :ref:`Python UTF-8 Mode <utf8-mode>` via |
| 1279 |
the ``-X utf8`` command line option, or the ``PYTHONUTF8=1`` environment |
| 1280 |
variable. See :envvar:`PYTHONUTF8` for enabling UTF-8 mode, and |
| 1281 |
:ref:`setting-envvars` for how to modify environment variables. |
| 1282 |
|
| 1283 |
When the :ref:`Python UTF-8 Mode <utf8-mode>` is enabled, you can still use the |
| 1284 |
system encoding (the ANSI Code Page) via the "mbcs" codec. |
| 1285 |
|
| 1286 |
Note that adding ``PYTHONUTF8=1`` to the default environment variables |
| 1287 |
will affect all Python 3.7+ applications on your system. |
| 1288 |
If you have any Python 3.7+ applications which rely on the legacy |
| 1289 |
system encoding, it is recommended to set the environment variable |
| 1290 |
temporarily or use the ``-X utf8`` command line option. |
| 1291 |
|
| 1292 |
.. note:: |
| 1293 |
Even when UTF-8 mode is disabled, Python uses UTF-8 by default |
| 1294 |
on Windows for: |
| 1295 |
|
| 1296 |
* Console I/O including standard I/O (see :pep:`528` for details). |
| 1297 |
* The :term:`filesystem encoding <filesystem encoding and error handler>` |
| 1298 |
(see :pep:`529` for details). |
| 1299 |
|
| 1300 |
|
| 1301 |
.. _windows_finding_modules: |
| 1302 |
|
| 1303 |
Finding modules |
| 1304 |
=============== |
| 1305 |
|
| 1306 |
These notes supplement the description at :ref:`sys-path-init` with |
| 1307 |
detailed Windows notes. |
| 1308 |
|
| 1309 |
When no ``._pth`` file is found, this is how :data:`sys.path` is populated on |
| 1310 |
Windows: |
| 1311 |
|
| 1312 |
* An empty entry is added at the start, which corresponds to the current |
| 1313 |
directory. |
| 1314 |
|
| 1315 |
* If the environment variable :envvar:`PYTHONPATH` exists, as described in |
| 1316 |
:ref:`using-on-envvars`, its entries are added next. Note that on Windows, |
| 1317 |
paths in this variable must be separated by semicolons, to distinguish them |
| 1318 |
from the colon used in drive identifiers (``C:\`` etc.). |
| 1319 |
|
| 1320 |
* Additional "application paths" can be added in the registry as subkeys of |
| 1321 |
:samp:`\\SOFTWARE\\Python\\PythonCore\\{version}\\PythonPath` under both the |
| 1322 |
``HKEY_CURRENT_USER`` and ``HKEY_LOCAL_MACHINE`` hives. Subkeys which have |
| 1323 |
semicolon-delimited path strings as their default value will cause each path |
| 1324 |
to be added to :data:`sys.path`. (Note that all known installers only use |
| 1325 |
HKLM, so HKCU is typically empty.) |
| 1326 |
|
| 1327 |
* If the environment variable :envvar:`PYTHONHOME` is set, it is assumed as |
| 1328 |
"Python Home". Otherwise, the path of the main Python executable is used to |
| 1329 |
locate a "landmark file" (either ``Lib\os.py`` or ``pythonXY.zip``) to deduce |
| 1330 |
the "Python Home". If a Python home is found, the relevant sub-directories |
| 1331 |
added to :data:`sys.path` (``Lib``, ``plat-win``, etc) are based on that |
| 1332 |
folder. Otherwise, the core Python path is constructed from the PythonPath |
| 1333 |
stored in the registry. |
| 1334 |
|
| 1335 |
* If the Python Home cannot be located, no :envvar:`PYTHONPATH` is specified in |
| 1336 |
the environment, and no registry entries can be found, a default path with |
| 1337 |
relative entries is used (e.g. ``.\Lib;.\plat-win``, etc). |
| 1338 |
|
| 1339 |
If a ``pyvenv.cfg`` file is found alongside the main executable or in the |
| 1340 |
directory one level above the executable, the following variations apply: |
| 1341 |
|
| 1342 |
* If ``home`` is an absolute path and :envvar:`PYTHONHOME` is not set, this |
| 1343 |
path is used instead of the path to the main executable when deducing the |
| 1344 |
home location. |
| 1345 |
|
| 1346 |
The end result of all this is: |
| 1347 |
|
| 1348 |
* When running :file:`python.exe`, or any other .exe in the main Python |
| 1349 |
directory (either an installed version, or directly from the PCbuild |
| 1350 |
directory), the core path is deduced, and the core paths in the registry are |
| 1351 |
ignored. Other "application paths" in the registry are always read. |
| 1352 |
|
| 1353 |
* When Python is hosted in another .exe (different directory, embedded via COM, |
| 1354 |
etc), the "Python Home" will not be deduced, so the core path from the |
| 1355 |
registry is used. Other "application paths" in the registry are always read. |
| 1356 |
|
| 1357 |
* If Python can't find its home and there are no registry value (frozen .exe, |
| 1358 |
some very strange installation setup) you get a path with some default, but |
| 1359 |
relative, paths. |
| 1360 |
|
| 1361 |
For those who want to bundle Python into their application or distribution, the |
| 1362 |
following advice will prevent conflicts with other installations: |
| 1363 |
|
| 1364 |
* Include a ``._pth`` file alongside your executable containing the |
| 1365 |
directories to include. This will ignore paths listed in the registry and |
| 1366 |
environment variables, and also ignore :mod:`site` unless ``import site`` is |
| 1367 |
listed. |
| 1368 |
|
| 1369 |
* If you are loading :file:`python3.dll` or :file:`python37.dll` in your own |
| 1370 |
executable, explicitly set :c:member:`PyConfig.module_search_paths` before |
| 1371 |
:c:func:`Py_InitializeFromConfig`. |
| 1372 |
|
| 1373 |
* Clear and/or overwrite :envvar:`PYTHONPATH` and set :envvar:`PYTHONHOME` |
| 1374 |
before launching :file:`python.exe` from your application. |
| 1375 |
|
| 1376 |
* If you cannot use the previous suggestions (for example, you are a |
| 1377 |
distribution that allows people to run :file:`python.exe` directly), ensure |
| 1378 |
that the landmark file (:file:`Lib\\os.py`) exists in your install directory. |
| 1379 |
(Note that it will not be detected inside a ZIP file, but a correctly named |
| 1380 |
ZIP file will be detected instead.) |
| 1381 |
|
| 1382 |
These will ensure that the files in a system-wide installation will not take |
| 1383 |
precedence over the copy of the standard library bundled with your application. |
| 1384 |
Otherwise, your users may experience problems using your application. Note that |
| 1385 |
the first suggestion is the best, as the others may still be susceptible to |
| 1386 |
non-standard paths in the registry and user site-packages. |
| 1387 |
|
| 1388 |
.. versionchanged:: 3.6 |
| 1389 |
|
| 1390 |
Add ``._pth`` file support and removes ``applocal`` option from |
| 1391 |
``pyvenv.cfg``. |
| 1392 |
|
| 1393 |
.. versionchanged:: 3.6 |
| 1394 |
|
| 1395 |
Add :file:`python{XX}.zip` as a potential landmark when directly adjacent |
| 1396 |
to the executable. |
| 1397 |
|
| 1398 |
.. deprecated:: 3.6 |
| 1399 |
|
| 1400 |
Modules specified in the registry under ``Modules`` (not ``PythonPath``) |
| 1401 |
may be imported by :class:`importlib.machinery.WindowsRegistryFinder`. |
| 1402 |
This finder is enabled on Windows in 3.6.0 and earlier, but may need to |
| 1403 |
be explicitly added to :data:`sys.meta_path` in the future. |
| 1404 |
|
| 1405 |
Additional modules |
| 1406 |
================== |
| 1407 |
|
| 1408 |
Even though Python aims to be portable among all platforms, there are features |
| 1409 |
that are unique to Windows. A couple of modules, both in the standard library |
| 1410 |
and external, and snippets exist to use these features. |
| 1411 |
|
| 1412 |
The Windows-specific standard modules are documented in |
| 1413 |
:ref:`mswin-specific-services`. |
| 1414 |
|
| 1415 |
PyWin32 |
| 1416 |
------- |
| 1417 |
|
| 1418 |
The :pypi:`PyWin32` module by Mark Hammond |
| 1419 |
is a collection of modules for advanced Windows-specific support. This includes |
| 1420 |
utilities for: |
| 1421 |
|
| 1422 |
* `Component Object Model |
| 1423 |
<https://learn.microsoft.com/windows/win32/com/component-object-model--com--portal>`_ |
| 1424 |
(COM) |
| 1425 |
* Win32 API calls |
| 1426 |
* Registry |
| 1427 |
* Event log |
| 1428 |
* `Microsoft Foundation Classes |
| 1429 |
<https://learn.microsoft.com/cpp/mfc/mfc-desktop-applications>`_ |
| 1430 |
(MFC) user interfaces |
| 1431 |
|
| 1432 |
`PythonWin <https://web.archive.org/web/20060524042422/ |
| 1433 |
https://www.python.org/windows/pythonwin/>`_ is a sample MFC application |
| 1434 |
shipped with PyWin32. It is an embeddable IDE with a built-in debugger. |
| 1435 |
|
| 1436 |
.. seealso:: |
| 1437 |
|
| 1438 |
`Win32 How Do I...? <https://timgolden.me.uk/python/win32_how_do_i.html>`_ |
| 1439 |
by Tim Golden |
| 1440 |
|
| 1441 |
`Python and COM <https://www.boddie.org.uk/python/COM.html>`_ |
| 1442 |
by David and Paul Boddie |
| 1443 |
|
| 1444 |
|
| 1445 |
cx_Freeze |
| 1446 |
--------- |
| 1447 |
|
| 1448 |
`cx_Freeze <https://cx-freeze.readthedocs.io/en/latest/>`_ |
| 1449 |
wraps Python scripts into executable Windows programs |
| 1450 |
(:file:`{*}.exe` files). When you have done this, you can distribute your |
| 1451 |
application without requiring your users to install Python. |
| 1452 |
|
| 1453 |
|
| 1454 |
Compiling Python on Windows |
| 1455 |
=========================== |
| 1456 |
|
| 1457 |
If you want to compile CPython yourself, first thing you should do is get the |
| 1458 |
`source <https://www.python.org/downloads/source/>`_. You can download either the |
| 1459 |
latest release's source or just grab a fresh `checkout |
| 1460 |
<https://devguide.python.org/setup/#get-the-source-code>`_. |
| 1461 |
|
| 1462 |
The source tree contains a build solution and project files for Microsoft |
| 1463 |
Visual Studio, which is the compiler used to build the official Python |
| 1464 |
releases. These files are in the :file:`PCbuild` directory. |
| 1465 |
|
| 1466 |
Check :file:`PCbuild/readme.txt` for general information on the build process. |
| 1467 |
|
| 1468 |
For extension modules, consult :ref:`building-on-windows`. |
| 1469 |
|
| 1470 |
|
| 1471 |
|
| 1472 |
.. _windows-full: |
| 1473 |
|
| 1474 |
The full installer (deprecated) |
| 1475 |
=============================== |
| 1476 |
|
| 1477 |
.. deprecated:: 3.14 |
| 1478 |
|
| 1479 |
This installer is deprecated since 3.14 and will not be produced for Python |
| 1480 |
3.16 or later. See :ref:`pymanager` for the modern installer. |
| 1481 |
|
| 1482 |
|
| 1483 |
Installation steps |
| 1484 |
------------------ |
| 1485 |
|
| 1486 |
Four Python |version| installers are available for download - two each for the |
| 1487 |
32-bit and 64-bit versions of the interpreter. The *web installer* is a small |
| 1488 |
initial download, and it will automatically download the required components as |
| 1489 |
necessary. The *offline installer* includes the components necessary for a |
| 1490 |
default installation and only requires an internet connection for optional |
| 1491 |
features. See :ref:`install-layout-option` for other ways to avoid downloading |
| 1492 |
during installation. |
| 1493 |
|
| 1494 |
After starting the installer, one of two options may be selected: |
| 1495 |
|
| 1496 |
.. image:: win_installer.png |
| 1497 |
|
| 1498 |
If you select "Install Now": |
| 1499 |
|
| 1500 |
* You will *not* need to be an administrator (unless a system update for the |
| 1501 |
C Runtime Library is required or you install the :ref:`launcher` for all |
| 1502 |
users) |
| 1503 |
* Python will be installed into your user directory |
| 1504 |
* The :ref:`launcher` will be installed according to the option at the bottom |
| 1505 |
of the first page |
| 1506 |
* The standard library, test suite, launcher and pip will be installed |
| 1507 |
* If selected, the install directory will be added to your :envvar:`PATH` |
| 1508 |
* Shortcuts will only be visible for the current user |
| 1509 |
|
| 1510 |
Selecting "Customize installation" will allow you to select the features to |
| 1511 |
install, the installation location and other options or post-install actions. |
| 1512 |
To install debugging symbols or binaries, you will need to use this option. |
| 1513 |
|
| 1514 |
To perform an all-users installation, you should select "Customize |
| 1515 |
installation". In this case: |
| 1516 |
|
| 1517 |
* You may be required to provide administrative credentials or approval |
| 1518 |
* Python will be installed into the Program Files directory |
| 1519 |
* The :ref:`launcher` will be installed into the Windows directory |
| 1520 |
* Optional features may be selected during installation |
| 1521 |
* The standard library can be pre-compiled to bytecode |
| 1522 |
* If selected, the install directory will be added to the system :envvar:`PATH` |
| 1523 |
* Shortcuts are available for all users |
| 1524 |
|
| 1525 |
|
| 1526 |
Removing the MAX_PATH limitation |
| 1527 |
-------------------------------- |
| 1528 |
|
| 1529 |
Windows historically has limited path lengths to 260 characters. This meant that |
| 1530 |
paths longer than this would not resolve and errors would result. |
| 1531 |
|
| 1532 |
In the latest versions of Windows, this limitation can be expanded to |
| 1533 |
approximately 32,000 characters. Your administrator will need to activate the |
| 1534 |
"Enable Win32 long paths" group policy, or set ``LongPathsEnabled`` to ``1`` |
| 1535 |
in the registry key |
| 1536 |
``HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem``. |
| 1537 |
|
| 1538 |
This allows the :func:`open` function, the :mod:`os` module and most other |
| 1539 |
path functionality to accept and return paths longer than 260 characters. |
| 1540 |
|
| 1541 |
After changing the above option, no further configuration is required. |
| 1542 |
|
| 1543 |
.. versionchanged:: 3.6 |
| 1544 |
|
| 1545 |
Support for long paths was enabled in Python. |
| 1546 |
|
| 1547 |
.. _install-quiet-option: |
| 1548 |
|
| 1549 |
Installing without UI |
| 1550 |
--------------------- |
| 1551 |
|
| 1552 |
All of the options available in the installer UI can also be specified from the |
| 1553 |
command line, allowing scripted installers to replicate an installation on many |
| 1554 |
machines without user interaction. These options may also be set without |
| 1555 |
suppressing the UI in order to change some of the defaults. |
| 1556 |
|
| 1557 |
The following options (found by executing the installer with ``/?``) can be |
| 1558 |
passed into the installer: |
| 1559 |
|
| 1560 |
+---------------------+--------------------------------------------------------+ |
| 1561 |
| Name | Description | |
| 1562 |
+=====================+========================================================+ |
| 1563 |
| /passive | to display progress without requiring user interaction | |
| 1564 |
+---------------------+--------------------------------------------------------+ |
| 1565 |
| /quiet | to install/uninstall without displaying any UI | |
| 1566 |
+---------------------+--------------------------------------------------------+ |
| 1567 |
| /simple | to prevent user customization | |
| 1568 |
+---------------------+--------------------------------------------------------+ |
| 1569 |
| /uninstall | to remove Python (without confirmation) | |
| 1570 |
+---------------------+--------------------------------------------------------+ |
| 1571 |
| /layout [directory] | to pre-download all components | |
| 1572 |
+---------------------+--------------------------------------------------------+ |
| 1573 |
| /log [filename] | to specify log files location | |
| 1574 |
+---------------------+--------------------------------------------------------+ |
| 1575 |
|
| 1576 |
All other options are passed as ``name=value``, where the value is usually |
| 1577 |
``0`` to disable a feature, ``1`` to enable a feature, or a path. The full list |
| 1578 |
of available options is shown below. |
| 1579 |
|
| 1580 |
+---------------------------+--------------------------------------+--------------------------+ |
| 1581 |
| Name | Description | Default | |
| 1582 |
+===========================+======================================+==========================+ |
| 1583 |
| InstallAllUsers | Perform a system-wide installation. | 0 | |
| 1584 |
+---------------------------+--------------------------------------+--------------------------+ |
| 1585 |
| TargetDir | The installation directory | Selected based on | |
| 1586 |
| | | InstallAllUsers | |
| 1587 |
+---------------------------+--------------------------------------+--------------------------+ |
| 1588 |
| DefaultAllUsersTargetDir | The default installation directory | :file:`%ProgramFiles%\\\ | |
| 1589 |
| | for all-user installs | Python X.Y` or :file:`\ | |
| 1590 |
| | | %ProgramFiles(x86)%\\\ | |
| 1591 |
| | | Python X.Y` | |
| 1592 |
+---------------------------+--------------------------------------+--------------------------+ |
| 1593 |
| DefaultJustForMeTargetDir | The default install directory for | :file:`%LocalAppData%\\\ | |
| 1594 |
| | just-for-me installs | Programs\\Python\\\ | |
| 1595 |
| | | PythonXY` or | |
| 1596 |
| | | :file:`%LocalAppData%\\\ | |
| 1597 |
| | | Programs\\Python\\\ | |
| 1598 |
| | | PythonXY-32` or | |
| 1599 |
| | | :file:`%LocalAppData%\\\ | |
| 1600 |
| | | Programs\\Python\\\ | |
| 1601 |
| | | PythonXY-64` | |
| 1602 |
+---------------------------+--------------------------------------+--------------------------+ |
| 1603 |
| DefaultCustomTargetDir | The default custom install directory | (empty) | |
| 1604 |
| | displayed in the UI | | |
| 1605 |
+---------------------------+--------------------------------------+--------------------------+ |
| 1606 |
| AssociateFiles | Create file associations if the | 1 | |
| 1607 |
| | launcher is also installed. | | |
| 1608 |
+---------------------------+--------------------------------------+--------------------------+ |
| 1609 |
| CompileAll | Compile all ``.py`` files to | 0 | |
| 1610 |
| | ``.pyc``. | | |
| 1611 |
+---------------------------+--------------------------------------+--------------------------+ |
| 1612 |
| PrependPath | Prepend install and Scripts | 0 | |
| 1613 |
| | directories to :envvar:`PATH` and | | |
| 1614 |
| | add ``.PY`` to :envvar:`PATHEXT` | | |
| 1615 |
+---------------------------+--------------------------------------+--------------------------+ |
| 1616 |
| AppendPath | Append install and Scripts | 0 | |
| 1617 |
| | directories to :envvar:`PATH` and | | |
| 1618 |
| | add ``.PY`` to :envvar:`PATHEXT` | | |
| 1619 |
+---------------------------+--------------------------------------+--------------------------+ |
| 1620 |
| Shortcuts | Create shortcuts for the interpreter,| 1 | |
| 1621 |
| | documentation and IDLE if installed. | | |
| 1622 |
+---------------------------+--------------------------------------+--------------------------+ |
| 1623 |
| Include_doc | Install Python manual | 1 | |
| 1624 |
+---------------------------+--------------------------------------+--------------------------+ |
| 1625 |
| Include_debug | Install debug binaries | 0 | |
| 1626 |
+---------------------------+--------------------------------------+--------------------------+ |
| 1627 |
| Include_dev | Install developer headers and | 1 | |
| 1628 |
| | libraries. Omitting this may lead to | | |
| 1629 |
| | an unusable installation. | | |
| 1630 |
+---------------------------+--------------------------------------+--------------------------+ |
| 1631 |
| Include_exe | Install :file:`python.exe` and | 1 | |
| 1632 |
| | related files. Omitting this may | | |
| 1633 |
| | lead to an unusable installation. | | |
| 1634 |
+---------------------------+--------------------------------------+--------------------------+ |
| 1635 |
| Include_launcher | Install :ref:`launcher`. | 1 | |
| 1636 |
+---------------------------+--------------------------------------+--------------------------+ |
| 1637 |
| InstallLauncherAllUsers | Installs the launcher for all | 1 | |
| 1638 |
| | users. Also requires | | |
| 1639 |
| | ``Include_launcher`` to be set to 1 | | |
| 1640 |
+---------------------------+--------------------------------------+--------------------------+ |
| 1641 |
| Include_lib | Install standard library and | 1 | |
| 1642 |
| | extension modules. Omitting this may | | |
| 1643 |
| | lead to an unusable installation. | | |
| 1644 |
+---------------------------+--------------------------------------+--------------------------+ |
| 1645 |
| Include_pip | Install bundled pip and setuptools | 1 | |
| 1646 |
+---------------------------+--------------------------------------+--------------------------+ |
| 1647 |
| Include_symbols | Install debugging symbols (``*.pdb``)| 0 | |
| 1648 |
+---------------------------+--------------------------------------+--------------------------+ |
| 1649 |
| Include_tcltk | Install Tcl/Tk support and IDLE | 1 | |
| 1650 |
+---------------------------+--------------------------------------+--------------------------+ |
| 1651 |
| Include_test | Install standard library test suite | 1 | |
| 1652 |
+---------------------------+--------------------------------------+--------------------------+ |
| 1653 |
| Include_tools | Install utility scripts | 1 | |
| 1654 |
+---------------------------+--------------------------------------+--------------------------+ |
| 1655 |
| LauncherOnly | Only installs the launcher. This | 0 | |
| 1656 |
| | will override most other options. | | |
| 1657 |
+---------------------------+--------------------------------------+--------------------------+ |
| 1658 |
| SimpleInstall | Disable most install UI | 0 | |
| 1659 |
+---------------------------+--------------------------------------+--------------------------+ |
| 1660 |
| SimpleInstallDescription | A custom message to display when the | (empty) | |
| 1661 |
| | simplified install UI is used. | | |
| 1662 |
+---------------------------+--------------------------------------+--------------------------+ |
| 1663 |
|
| 1664 |
For example, to silently install a default, system-wide Python installation, |
| 1665 |
you could use the following command (from an elevated command prompt):: |
| 1666 |
|
| 1667 |
python-3.9.0.exe /quiet InstallAllUsers=1 PrependPath=1 Include_test=0 |
| 1668 |
|
| 1669 |
To allow users to easily install a personal copy of Python without the test |
| 1670 |
suite, you could provide a shortcut with the following command. This will |
| 1671 |
display a simplified initial page and disallow customization:: |
| 1672 |
|
| 1673 |
python-3.9.0.exe InstallAllUsers=0 Include_launcher=0 Include_test=0 |
| 1674 |
SimpleInstall=1 SimpleInstallDescription="Just for me, no test suite." |
| 1675 |
|
| 1676 |
(Note that omitting the launcher also omits file associations, and is only |
| 1677 |
recommended for per-user installs when there is also a system-wide installation |
| 1678 |
that included the launcher.) |
| 1679 |
|
| 1680 |
The options listed above can also be provided in a file named ``unattend.xml`` |
| 1681 |
alongside the executable. This file specifies a list of options and values. |
| 1682 |
When a value is provided as an attribute, it will be converted to a number if |
| 1683 |
possible. Values provided as element text are always left as strings. This |
| 1684 |
example file sets the same options as the previous example: |
| 1685 |
|
| 1686 |
.. code-block:: xml |
| 1687 |
|
| 1688 |
<Options> |
| 1689 |
<Option Name="InstallAllUsers" Value="no" /> |
| 1690 |
<Option Name="Include_launcher" Value="0" /> |
| 1691 |
<Option Name="Include_test" Value="no" /> |
| 1692 |
<Option Name="SimpleInstall" Value="yes" /> |
| 1693 |
<Option Name="SimpleInstallDescription">Just for me, no test suite</Option> |
| 1694 |
</Options> |
| 1695 |
|
| 1696 |
.. _install-layout-option: |
| 1697 |
|
| 1698 |
Installing without downloading |
| 1699 |
------------------------------ |
| 1700 |
|
| 1701 |
As some features of Python are not included in the initial installer download, |
| 1702 |
selecting those features may require an internet connection. To avoid this |
| 1703 |
need, all possible components may be downloaded on-demand to create a complete |
| 1704 |
*layout* that will no longer require an internet connection regardless of the |
| 1705 |
selected features. Note that this download may be bigger than required, but |
| 1706 |
where a large number of installations are going to be performed it is very |
| 1707 |
useful to have a locally cached copy. |
| 1708 |
|
| 1709 |
Execute the following command from Command Prompt to download all possible |
| 1710 |
required files. Remember to substitute ``python-3.9.0.exe`` for the actual |
| 1711 |
name of your installer, and to create layouts in their own directories to |
| 1712 |
avoid collisions between files with the same name. |
| 1713 |
|
| 1714 |
:: |
| 1715 |
|
| 1716 |
python-3.9.0.exe /layout [optional target directory] |
| 1717 |
|
| 1718 |
You may also specify the ``/quiet`` option to hide the progress display. |
| 1719 |
|
| 1720 |
Modifying an install |
| 1721 |
-------------------- |
| 1722 |
|
| 1723 |
Once Python has been installed, you can add or remove features through the |
| 1724 |
Programs and Features tool that is part of Windows. Select the Python entry and |
| 1725 |
choose "Uninstall/Change" to open the installer in maintenance mode. |
| 1726 |
|
| 1727 |
"Modify" allows you to add or remove features by modifying the checkboxes - |
| 1728 |
unchanged checkboxes will not install or remove anything. Some options cannot be |
| 1729 |
changed in this mode, such as the install directory; to modify these, you will |
| 1730 |
need to remove and then reinstall Python completely. |
| 1731 |
|
| 1732 |
"Repair" will verify all the files that should be installed using the current |
| 1733 |
settings and replace any that have been removed or modified. |
| 1734 |
|
| 1735 |
"Uninstall" will remove Python entirely, with the exception of the |
| 1736 |
:ref:`launcher`, which has its own entry in Programs and Features. |
| 1737 |
|
| 1738 |
|
| 1739 |
Installing free-threaded binaries |
| 1740 |
--------------------------------- |
| 1741 |
|
| 1742 |
.. versionadded:: 3.13 |
| 1743 |
|
| 1744 |
To install pre-built binaries with free-threading enabled (see :pep:`703`), you |
| 1745 |
should select "Customize installation". The second page of options includes the |
| 1746 |
"Download free-threaded binaries" checkbox. |
| 1747 |
|
| 1748 |
.. image:: win_install_freethreaded.png |
| 1749 |
|
| 1750 |
Selecting this option will download and install additional binaries to the same |
| 1751 |
location as the main Python install. The main executable is called |
| 1752 |
``python3.13t.exe``, and other binaries either receive a ``t`` suffix or a full |
| 1753 |
ABI suffix. Python source files and bundled third-party dependencies are shared |
| 1754 |
with the main install. |
| 1755 |
|
| 1756 |
The free-threaded version is registered as a regular Python install with the |
| 1757 |
tag ``3.13t`` (with a ``-32`` or ``-arm64`` suffix as normal for those |
| 1758 |
platforms). This allows tools to discover it, and for the :ref:`launcher` to |
| 1759 |
support ``py.exe -3.13t``. Note that the launcher will interpret ``py.exe -3`` |
| 1760 |
(or a ``python3`` shebang) as "the latest 3.x install", which will prefer the |
| 1761 |
free-threaded binaries over the regular ones, while ``py.exe -3.13`` will not. |
| 1762 |
If you use the short style of option, you may prefer to not install the |
| 1763 |
free-threaded binaries at this time. |
| 1764 |
|
| 1765 |
To specify the install option at the command line, use |
| 1766 |
``Include_freethreaded=1``. See :ref:`install-layout-option` for instructions on |
| 1767 |
pre-emptively downloading the additional binaries for offline install. The |
| 1768 |
options to include debug symbols and binaries also apply to the free-threaded |
| 1769 |
builds. |
| 1770 |
|
| 1771 |
Free-threaded binaries are also available :ref:`on nuget.org <windows-nuget>`. |
| 1772 |
|
| 1773 |
|
| 1774 |
Python launcher for Windows (deprecated) |
| 1775 |
======================================== |
| 1776 |
|
| 1777 |
.. deprecated:: 3.14 |
| 1778 |
|
| 1779 |
The launcher and this documentation have been superseded by the Python |
| 1780 |
Install Manager described above. This is preserved temporarily for historical |
| 1781 |
interest. |
| 1782 |
|
| 1783 |
.. versionadded:: 3.3 |
| 1784 |
|
| 1785 |
The Python launcher for Windows is a utility which aids in locating and |
| 1786 |
executing of different Python versions. It allows scripts (or the |
| 1787 |
command-line) to indicate a preference for a specific Python version, and |
| 1788 |
will locate and execute that version. |
| 1789 |
|
| 1790 |
Unlike the :envvar:`PATH` variable, the launcher will correctly select the most |
| 1791 |
appropriate version of Python. It will prefer per-user installations over |
| 1792 |
system-wide ones, and orders by language version rather than using the most |
| 1793 |
recently installed version. |
| 1794 |
|
| 1795 |
The launcher was originally specified in :pep:`397`. |
| 1796 |
|
| 1797 |
Getting started |
| 1798 |
--------------- |
| 1799 |
|
| 1800 |
From the command-line |
| 1801 |
^^^^^^^^^^^^^^^^^^^^^ |
| 1802 |
|
| 1803 |
.. versionchanged:: 3.6 |
| 1804 |
|
| 1805 |
System-wide installations of Python 3.3 and later will put the launcher on your |
| 1806 |
:envvar:`PATH`. The launcher is compatible with all available versions of |
| 1807 |
Python, so it does not matter which version is installed. To check that the |
| 1808 |
launcher is available, execute the following command in Command Prompt:: |
| 1809 |
|
| 1810 |
py |
| 1811 |
|
| 1812 |
You should find that the latest version of Python you have installed is |
| 1813 |
started - it can be exited as normal, and any additional command-line |
| 1814 |
arguments specified will be sent directly to Python. |
| 1815 |
|
| 1816 |
If you have multiple versions of Python installed (e.g., 3.7 and |version|) you |
| 1817 |
will have noticed that Python |version| was started - to launch Python 3.7, try |
| 1818 |
the command:: |
| 1819 |
|
| 1820 |
py -3.7 |
| 1821 |
|
| 1822 |
If you want the latest version of Python 2 you have installed, try the |
| 1823 |
command:: |
| 1824 |
|
| 1825 |
py -2 |
| 1826 |
|
| 1827 |
If you see the following error, you do not have the launcher installed:: |
| 1828 |
|
| 1829 |
'py' is not recognized as an internal or external command, |
| 1830 |
operable program or batch file. |
| 1831 |
|
| 1832 |
The command:: |
| 1833 |
|
| 1834 |
py --list |
| 1835 |
|
| 1836 |
displays the currently installed version(s) of Python. |
| 1837 |
|
| 1838 |
The ``-x.y`` argument is the short form of the ``-V:Company/Tag`` argument, |
| 1839 |
which allows selecting a specific Python runtime, including those that may have |
| 1840 |
come from somewhere other than python.org. Any runtime registered by following |
| 1841 |
:pep:`514` will be discoverable. The ``--list`` command lists all available |
| 1842 |
runtimes using the ``-V:`` format. |
| 1843 |
|
| 1844 |
When using the ``-V:`` argument, specifying the Company will limit selection to |
| 1845 |
runtimes from that provider, while specifying only the Tag will select from all |
| 1846 |
providers. Note that omitting the slash implies a tag:: |
| 1847 |
|
| 1848 |
# Select any '3.*' tagged runtime |
| 1849 |
py -V:3 |
| 1850 |
|
| 1851 |
# Select any 'PythonCore' released runtime |
| 1852 |
py -V:PythonCore/ |
| 1853 |
|
| 1854 |
# Select PythonCore's latest Python 3 runtime |
| 1855 |
py -V:PythonCore/3 |
| 1856 |
|
| 1857 |
The short form of the argument (``-3``) only ever selects from core Python |
| 1858 |
releases, and not other distributions. However, the longer form (``-V:3``) will |
| 1859 |
select from any. |
| 1860 |
|
| 1861 |
The Company is matched on the full string, case-insensitive. The Tag is matched |
| 1862 |
on either the full string, or a prefix, provided the next character is a dot or a |
| 1863 |
hyphen. This allows ``-V:3.1`` to match ``3.1-32``, but not ``3.10``. Tags are |
| 1864 |
sorted using numerical ordering (``3.10`` is newer than ``3.1``), but are |
| 1865 |
compared using text (``-V:3.01`` does not match ``3.1``). |
| 1866 |
|
| 1867 |
|
| 1868 |
Virtual environments |
| 1869 |
^^^^^^^^^^^^^^^^^^^^ |
| 1870 |
|
| 1871 |
.. versionadded:: 3.5 |
| 1872 |
|
| 1873 |
If the launcher is run with no explicit Python version specification, and a |
| 1874 |
virtual environment (created with the standard library :mod:`venv` module or |
| 1875 |
the external ``virtualenv`` tool) active, the launcher will run the virtual |
| 1876 |
environment's interpreter rather than the global one. To run the global |
| 1877 |
interpreter, either deactivate the virtual environment, or explicitly specify |
| 1878 |
the global Python version. |
| 1879 |
|
| 1880 |
From a script |
| 1881 |
^^^^^^^^^^^^^ |
| 1882 |
|
| 1883 |
Let's create a test Python script - create a file called ``hello.py`` with the |
| 1884 |
following contents |
| 1885 |
|
| 1886 |
.. code-block:: python |
| 1887 |
|
| 1888 |
#! python |
| 1889 |
import sys |
| 1890 |
sys.stdout.write("hello from Python %s\n" % (sys.version,)) |
| 1891 |
|
| 1892 |
From the directory in which hello.py lives, execute the command:: |
| 1893 |
|
| 1894 |
py hello.py |
| 1895 |
|
| 1896 |
You should notice the version number of your latest Python 2.x installation |
| 1897 |
is printed. Now try changing the first line to be: |
| 1898 |
|
| 1899 |
.. code-block:: python |
| 1900 |
|
| 1901 |
#! python3 |
| 1902 |
|
| 1903 |
Re-executing the command should now print the latest Python 3.x information. |
| 1904 |
As with the above command-line examples, you can specify a more explicit |
| 1905 |
version qualifier. Assuming you have Python 3.7 installed, try changing |
| 1906 |
the first line to ``#! python3.7`` and you should find the 3.7 |
| 1907 |
version information printed. |
| 1908 |
|
| 1909 |
Note that unlike interactive use, a bare "python" will use the latest |
| 1910 |
version of Python 2.x that you have installed. This is for backward |
| 1911 |
compatibility and for compatibility with Unix, where the command ``python`` |
| 1912 |
typically refers to Python 2. |
| 1913 |
|
| 1914 |
From file associations |
| 1915 |
^^^^^^^^^^^^^^^^^^^^^^ |
| 1916 |
|
| 1917 |
The launcher should have been associated with Python files (i.e. ``.py``, |
| 1918 |
``.pyw``, ``.pyc`` files) when it was installed. This means that |
| 1919 |
when you double-click on one of these files from Windows explorer the launcher |
| 1920 |
will be used, and therefore you can use the same facilities described above to |
| 1921 |
have the script specify the version which should be used. |
| 1922 |
|
| 1923 |
The key benefit of this is that a single launcher can support multiple Python |
| 1924 |
versions at the same time depending on the contents of the first line. |
| 1925 |
|
| 1926 |
Shebang lines |
| 1927 |
------------- |
| 1928 |
|
| 1929 |
If the first line of a script file starts with ``#!``, it is known as a |
| 1930 |
"shebang" line. Linux and other Unix like operating systems have native |
| 1931 |
support for such lines and they are commonly used on such systems to indicate |
| 1932 |
how a script should be executed. This launcher allows the same facilities to |
| 1933 |
be used with Python scripts on Windows and the examples above demonstrate their |
| 1934 |
use. |
| 1935 |
|
| 1936 |
To allow shebang lines in Python scripts to be portable between Unix and |
| 1937 |
Windows, this launcher supports a number of 'virtual' commands to specify |
| 1938 |
which interpreter to use. The supported virtual commands are: |
| 1939 |
|
| 1940 |
* ``/usr/bin/env`` |
| 1941 |
* ``/usr/bin/python`` |
| 1942 |
* ``/usr/local/bin/python`` |
| 1943 |
* ``python`` |
| 1944 |
|
| 1945 |
For example, if the first line of your script starts with |
| 1946 |
|
| 1947 |
.. code-block:: sh |
| 1948 |
|
| 1949 |
#! /usr/bin/python |
| 1950 |
|
| 1951 |
The default Python or an active virtual environment will be located and used. |
| 1952 |
As many Python scripts written to work on Unix will already have this line, |
| 1953 |
you should find these scripts can be used by the launcher without modification. |
| 1954 |
If you are writing a new script on Windows which you hope will be useful on |
| 1955 |
Unix, you should use one of the shebang lines starting with ``/usr``. |
| 1956 |
|
| 1957 |
Any of the above virtual commands can be suffixed with an explicit version |
| 1958 |
(either just the major version, or the major and minor version). |
| 1959 |
Furthermore the 32-bit version can be requested by adding "-32" after the |
| 1960 |
minor version. I.e. ``/usr/bin/python3.7-32`` will request usage of the |
| 1961 |
32-bit Python 3.7. If a virtual environment is active, the version will be |
| 1962 |
ignored and the environment will be used. |
| 1963 |
|
| 1964 |
.. versionadded:: 3.7 |
| 1965 |
|
| 1966 |
Beginning with python launcher 3.7 it is possible to request 64-bit version |
| 1967 |
by the "-64" suffix. Furthermore it is possible to specify a major and |
| 1968 |
architecture without minor (i.e. ``/usr/bin/python3-64``). |
| 1969 |
|
| 1970 |
.. versionchanged:: 3.11 |
| 1971 |
|
| 1972 |
The "-64" suffix is deprecated, and now implies "any architecture that is |
| 1973 |
not provably i386/32-bit". To request a specific environment, use the new |
| 1974 |
:samp:`-V:{TAG}` argument with the complete tag. |
| 1975 |
|
| 1976 |
.. versionchanged:: 3.13 |
| 1977 |
|
| 1978 |
Virtual commands referencing ``python`` now prefer an active virtual |
| 1979 |
environment rather than searching :envvar:`PATH`. This handles cases where |
| 1980 |
the shebang specifies ``/usr/bin/env python3`` but :file:`python3.exe` is |
| 1981 |
not present in the active environment. |
| 1982 |
|
| 1983 |
The ``/usr/bin/env`` form of shebang line has one further special property. |
| 1984 |
Before looking for installed Python interpreters, this form will search the |
| 1985 |
executable :envvar:`PATH` for a Python executable matching the name provided |
| 1986 |
as the first argument. This corresponds to the behaviour of the Unix ``env`` |
| 1987 |
program, which performs a :envvar:`PATH` search. |
| 1988 |
If an executable matching the first argument after the ``env`` command cannot |
| 1989 |
be found, but the argument starts with ``python``, it will be handled as |
| 1990 |
described for the other virtual commands. |
| 1991 |
The environment variable :envvar:`!PYLAUNCHER_NO_SEARCH_PATH` may be set |
| 1992 |
(to any value) to skip this search of :envvar:`PATH`. |
| 1993 |
|
| 1994 |
Shebang lines that do not match any of these patterns are looked up in the |
| 1995 |
``[commands]`` section of the launcher's :ref:`.INI file <launcher-ini>`. |
| 1996 |
This may be used to handle certain commands in a way that makes sense for your |
| 1997 |
system. The name of the command must be a single argument (no spaces in the |
| 1998 |
shebang executable), and the value substituted is the full path to the |
| 1999 |
executable (additional arguments specified in the .INI will be quoted as part |
| 2000 |
of the filename). |
| 2001 |
|
| 2002 |
.. code-block:: ini |
| 2003 |
|
| 2004 |
[commands] |
| 2005 |
/bin/xpython=C:\Program Files\XPython\python.exe |
| 2006 |
|
| 2007 |
Any commands not found in the .INI file are treated as **Windows** executable |
| 2008 |
paths that are absolute or relative to the directory containing the script file. |
| 2009 |
This is a convenience for Windows-only scripts, such as those generated by an |
| 2010 |
installer, since the behavior is not compatible with Unix-style shells. |
| 2011 |
These paths may be quoted, and may include multiple arguments, after which the |
| 2012 |
path to the script and any additional arguments will be appended. |
| 2013 |
|
| 2014 |
|
| 2015 |
Arguments in shebang lines |
| 2016 |
-------------------------- |
| 2017 |
|
| 2018 |
The shebang lines can also specify additional options to be passed to the |
| 2019 |
Python interpreter. For example, if you have a shebang line: |
| 2020 |
|
| 2021 |
.. code-block:: sh |
| 2022 |
|
| 2023 |
#! /usr/bin/python -v |
| 2024 |
|
| 2025 |
Then Python will be started with the ``-v`` option |
| 2026 |
|
| 2027 |
Customization |
| 2028 |
------------- |
| 2029 |
|
| 2030 |
.. _launcher-ini: |
| 2031 |
|
| 2032 |
Customization via INI files |
| 2033 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 2034 |
|
| 2035 |
Two .ini files will be searched by the launcher - ``py.ini`` in the current |
| 2036 |
user's application data directory (``%LOCALAPPDATA%`` or ``$env:LocalAppData``) |
| 2037 |
and ``py.ini`` in the same directory as the launcher. The same .ini files are |
| 2038 |
used for both the 'console' version of the launcher (i.e. py.exe) and for the |
| 2039 |
'windows' version (i.e. pyw.exe). |
| 2040 |
|
| 2041 |
Customization specified in the "application directory" will have precedence over |
| 2042 |
the one next to the executable, so a user, who may not have write access to the |
| 2043 |
.ini file next to the launcher, can override commands in that global .ini file. |
| 2044 |
|
| 2045 |
Customizing default Python versions |
| 2046 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 2047 |
|
| 2048 |
In some cases, a version qualifier can be included in a command to dictate |
| 2049 |
which version of Python will be used by the command. A version qualifier |
| 2050 |
starts with a major version number and can optionally be followed by a period |
| 2051 |
('.') and a minor version specifier. Furthermore it is possible to specify |
| 2052 |
if a 32 or 64 bit implementation shall be requested by adding "-32" or "-64". |
| 2053 |
|
| 2054 |
For example, a shebang line of ``#!python`` has no version qualifier, while |
| 2055 |
``#!python3`` has a version qualifier which specifies only a major version. |
| 2056 |
|
| 2057 |
If no version qualifiers are found in a command, the environment |
| 2058 |
variable :envvar:`!PY_PYTHON` can be set to specify the default version |
| 2059 |
qualifier. If it is not set, the default is "3". The variable can |
| 2060 |
specify any value that may be passed on the command line, such as "3", |
| 2061 |
"3.7", "3.7-32" or "3.7-64". (Note that the "-64" option is only |
| 2062 |
available with the launcher included with Python 3.7 or newer.) |
| 2063 |
|
| 2064 |
If no minor version qualifiers are found, the environment variable |
| 2065 |
``PY_PYTHON{major}`` (where ``{major}`` is the current major version qualifier |
| 2066 |
as determined above) can be set to specify the full version. If no such option |
| 2067 |
is found, the launcher will enumerate the installed Python versions and use |
| 2068 |
the latest minor release found for the major version, which is likely, |
| 2069 |
although not guaranteed, to be the most recently installed version in that |
| 2070 |
family. |
| 2071 |
|
| 2072 |
On 64-bit Windows with both 32-bit and 64-bit implementations of the same |
| 2073 |
(major.minor) Python version installed, the 64-bit version will always be |
| 2074 |
preferred. This will be true for both 32-bit and 64-bit implementations of the |
| 2075 |
launcher - a 32-bit launcher will prefer to execute a 64-bit Python installation |
| 2076 |
of the specified version if available. This is so the behavior of the launcher |
| 2077 |
can be predicted knowing only what versions are installed on the PC and |
| 2078 |
without regard to the order in which they were installed (i.e., without knowing |
| 2079 |
whether a 32 or 64-bit version of Python and corresponding launcher was |
| 2080 |
installed last). As noted above, an optional "-32" or "-64" suffix can be |
| 2081 |
used on a version specifier to change this behaviour. |
| 2082 |
|
| 2083 |
Examples: |
| 2084 |
|
| 2085 |
* If no relevant options are set, the commands ``python`` and |
| 2086 |
``python2`` will use the latest Python 2.x version installed and |
| 2087 |
the command ``python3`` will use the latest Python 3.x installed. |
| 2088 |
|
| 2089 |
* The command ``python3.7`` will not consult any |
| 2090 |
options at all as the versions are fully specified. |
| 2091 |
|
| 2092 |
* If ``PY_PYTHON=3``, the commands ``python`` and ``python3`` will both use |
| 2093 |
the latest installed Python 3 version. |
| 2094 |
|
| 2095 |
* If ``PY_PYTHON=3.7-32``, the command ``python`` will use the 32-bit |
| 2096 |
implementation of 3.7 whereas the command ``python3`` will use the latest |
| 2097 |
installed Python (PY_PYTHON was not considered at all as a major |
| 2098 |
version was specified.) |
| 2099 |
|
| 2100 |
* If ``PY_PYTHON=3`` and ``PY_PYTHON3=3.7``, the commands |
| 2101 |
``python`` and ``python3`` will both use specifically 3.7 |
| 2102 |
|
| 2103 |
In addition to environment variables, the same settings can be configured |
| 2104 |
in the .INI file used by the launcher. The section in the INI file is |
| 2105 |
called ``[defaults]`` and the key name will be the same as the |
| 2106 |
environment variables without the leading ``PY_`` prefix (and note that |
| 2107 |
the key names in the INI file are case insensitive.) The contents of |
| 2108 |
an environment variable will override things specified in the INI file. |
| 2109 |
|
| 2110 |
For example: |
| 2111 |
|
| 2112 |
* Setting ``PY_PYTHON=3.7`` is equivalent to the INI file containing: |
| 2113 |
|
| 2114 |
.. code-block:: ini |
| 2115 |
|
| 2116 |
[defaults] |
| 2117 |
python=3.7 |
| 2118 |
|
| 2119 |
* Setting ``PY_PYTHON=3`` and ``PY_PYTHON3=3.7`` is equivalent to the INI file |
| 2120 |
containing: |
| 2121 |
|
| 2122 |
.. code-block:: ini |
| 2123 |
|
| 2124 |
[defaults] |
| 2125 |
python=3 |
| 2126 |
python3=3.7 |
| 2127 |
|
| 2128 |
Diagnostics |
| 2129 |
----------- |
| 2130 |
|
| 2131 |
If an environment variable :envvar:`!PYLAUNCHER_DEBUG` is set (to any value), the |
| 2132 |
launcher will print diagnostic information to stderr (i.e. to the console). |
| 2133 |
While this information manages to be simultaneously verbose *and* terse, it |
| 2134 |
should allow you to see what versions of Python were located, why a |
| 2135 |
particular version was chosen and the exact command-line used to execute the |
| 2136 |
target Python. It is primarily intended for testing and debugging. |
| 2137 |
|
| 2138 |
Dry run |
| 2139 |
------- |
| 2140 |
|
| 2141 |
If an environment variable :envvar:`!PYLAUNCHER_DRYRUN` is set (to any value), |
| 2142 |
the launcher will output the command it would have run, but will not actually |
| 2143 |
launch Python. This may be useful for tools that want to use the launcher to |
| 2144 |
detect and then launch Python directly. Note that the command written to |
| 2145 |
standard output is always encoded using UTF-8, and may not render correctly in |
| 2146 |
the console. |
| 2147 |
|
| 2148 |
Install on demand |
| 2149 |
----------------- |
| 2150 |
|
| 2151 |
If an environment variable :envvar:`!PYLAUNCHER_ALLOW_INSTALL` is set (to any |
| 2152 |
value), and the requested Python version is not installed but is available on |
| 2153 |
the Microsoft Store, the launcher will attempt to install it. This may require |
| 2154 |
user interaction to complete, and you may need to run the command again. |
| 2155 |
|
| 2156 |
An additional :envvar:`!PYLAUNCHER_ALWAYS_INSTALL` variable causes the launcher |
| 2157 |
to always try to install Python, even if it is detected. This is mainly intended |
| 2158 |
for testing (and should be used with :envvar:`!PYLAUNCHER_DRYRUN`). |
| 2159 |
|
| 2160 |
Return codes |
| 2161 |
------------ |
| 2162 |
|
| 2163 |
The following exit codes may be returned by the Python launcher. Unfortunately, |
| 2164 |
there is no way to distinguish these from the exit code of Python itself. |
| 2165 |
|
| 2166 |
The names of codes are as used in the sources, and are only for reference. There |
| 2167 |
is no way to access or resolve them apart from reading this page. Entries are |
| 2168 |
listed in alphabetical order of names. |
| 2169 |
|
| 2170 |
+-------------------+-------+-----------------------------------------------+ |
| 2171 |
| Name | Value | Description | |
| 2172 |
+===================+=======+===============================================+ |
| 2173 |
| RC_BAD_VENV_CFG | 107 | A :file:`pyvenv.cfg` was found but is corrupt.| |
| 2174 |
+-------------------+-------+-----------------------------------------------+ |
| 2175 |
| RC_CREATE_PROCESS | 101 | Failed to launch Python. | |
| 2176 |
+-------------------+-------+-----------------------------------------------+ |
| 2177 |
| RC_INSTALLING | 111 | An install was started, but the command will | |
| 2178 |
| | | need to be re-run after it completes. | |
| 2179 |
+-------------------+-------+-----------------------------------------------+ |
| 2180 |
| RC_INTERNAL_ERROR | 109 | Unexpected error. Please report a bug. | |
| 2181 |
+-------------------+-------+-----------------------------------------------+ |
| 2182 |
| RC_NO_COMMANDLINE | 108 | Unable to obtain command line from the | |
| 2183 |
| | | operating system. | |
| 2184 |
+-------------------+-------+-----------------------------------------------+ |
| 2185 |
| RC_NO_PYTHON | 103 | Unable to locate the requested version. | |
| 2186 |
+-------------------+-------+-----------------------------------------------+ |
| 2187 |
| RC_NO_VENV_CFG | 106 | A :file:`pyvenv.cfg` was required but not | |
| 2188 |
| | | found. | |
| 2189 |
+-------------------+-------+-----------------------------------------------+ |
| 2190 |
|