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