Debian Codegraph @

Doc/using/windows.rst

raw
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