Debian Codegraph @

Doc/using/windows.rst

raw
1 .. highlight:: none
2
3 .. _using-on-windows:
4
5 *************************
6 Using Python on Windows
7 *************************
8
9 .. sectionauthor:: Robert Lehmann <[email protected]>
10 .. sectionauthor:: Steve Dower <[email protected]>
11
12 This document aims to give an overview of Windows-specific behaviour you should
13 know about when using Python on Microsoft Windows.
14
15 Unlike most Unix systems and services, Windows does not include a system
16 supported installation of Python. To make Python available, the CPython team
17 has compiled Windows installers with every `release
18 <https://www.python.org/downloads/>`_ for many years. These installers
19 are primarily intended to add a per-user installation of Python, with the
20 core interpreter and library being used by a single user. The installer is also
21 able to install for all users of a single machine, and a separate ZIP file is
22 available for application-local distributions.
23
24 As specified in :pep:`11`, a Python release only supports a Windows platform
25 while Microsoft considers the platform under extended support. This means that
26 Python |version| supports Windows 8.1 and newer. If you require Windows 7
27 support, please install Python 3.8.
28
29 There are a number of different installers available for Windows, each with
30 certain benefits and downsides.
31
32 :ref:`windows-full` contains all components and is the best option for
33 developers using Python for any kind of project.
34
35 :ref:`windows-store` is a simple installation of Python that is suitable for
36 running scripts and packages, and using IDLE or other development environments.
37 It requires Windows 10 and above, but can be safely installed without corrupting other
38 programs. It also provides many convenient commands for launching Python and
39 its tools.
40
41 :ref:`windows-nuget` are lightweight installations intended for continuous
42 integration systems. It can be used to build Python packages or run scripts,
43 but is not updateable and has no user interface tools.
44
45 :ref:`windows-embeddable` is a minimal package of Python suitable for
46 embedding into a larger application.
47
48
49 .. _windows-full:
50
51 The full installer
52 ==================
53
54 Installation steps
55 ------------------
56
57 Four Python |version| installers are available for download - two each for the
58 32-bit and 64-bit versions of the interpreter. The *web installer* is a small
59 initial download, and it will automatically download the required components as
60 necessary. The *offline installer* includes the components necessary for a
61 default installation and only requires an internet connection for optional
62 features. See :ref:`install-layout-option` for other ways to avoid downloading
63 during installation.
64
65 After starting the installer, one of two options may be selected:
66
67 .. image:: win_installer.png
68
69 If you select "Install Now":
70
71 * You will *not* need to be an administrator (unless a system update for the
72 C Runtime Library is required or you install the :ref:`launcher` for all
73 users)
74 * Python will be installed into your user directory
75 * The :ref:`launcher` will be installed according to the option at the bottom
76 of the first page
77 * The standard library, test suite, launcher and pip will be installed
78 * If selected, the install directory will be added to your :envvar:`PATH`
79 * Shortcuts will only be visible for the current user
80
81 Selecting "Customize installation" will allow you to select the features to
82 install, the installation location and other options or post-install actions.
83 To install debugging symbols or binaries, you will need to use this option.
84
85 To perform an all-users installation, you should select "Customize
86 installation". In this case:
87
88 * You may be required to provide administrative credentials or approval
89 * Python will be installed into the Program Files directory
90 * The :ref:`launcher` will be installed into the Windows directory
91 * Optional features may be selected during installation
92 * The standard library can be pre-compiled to bytecode
93 * If selected, the install directory will be added to the system :envvar:`PATH`
94 * Shortcuts are available for all users
95
96 .. _max-path:
97
98 Removing the MAX_PATH Limitation
99 --------------------------------
100
101 Windows historically has limited path lengths to 260 characters. This meant that
102 paths longer than this would not resolve and errors would result.
103
104 In the latest versions of Windows, this limitation can be expanded to
105 approximately 32,000 characters. Your administrator will need to activate the
106 "Enable Win32 long paths" group policy, or set ``LongPathsEnabled`` to ``1``
107 in the registry key
108 ``HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem``.
109
110 This allows the :func:`open` function, the :mod:`os` module and most other
111 path functionality to accept and return paths longer than 260 characters.
112
113 After changing the above option, no further configuration is required.
114
115 .. versionchanged:: 3.6
116
117 Support for long paths was enabled in Python.
118
119 .. _install-quiet-option:
120
121 Installing Without UI
122 ---------------------
123
124 All of the options available in the installer UI can also be specified from the
125 command line, allowing scripted installers to replicate an installation on many
126 machines without user interaction. These options may also be set without
127 suppressing the UI in order to change some of the defaults.
128
129 The following options (found by executing the installer with ``/?``) can be
130 passed into the installer:
131
132 +---------------------+--------------------------------------------------------+
133 | Name | Description |
134 +=====================+========================================================+
135 | /passive | to display progress without requiring user interaction |
136 +---------------------+--------------------------------------------------------+
137 | /quiet | to install/uninstall without displaying any UI |
138 +---------------------+--------------------------------------------------------+
139 | /simple | to prevent user customization |
140 +---------------------+--------------------------------------------------------+
141 | /uninstall | to remove Python (without confirmation) |
142 +---------------------+--------------------------------------------------------+
143 | /layout [directory] | to pre-download all components |
144 +---------------------+--------------------------------------------------------+
145 | /log [filename] | to specify log files location |
146 +---------------------+--------------------------------------------------------+
147
148 All other options are passed as ``name=value``, where the value is usually
149 ``0`` to disable a feature, ``1`` to enable a feature, or a path. The full list
150 of available options is shown below.
151
152 +---------------------------+--------------------------------------+--------------------------+
153 | Name | Description | Default |
154 +===========================+======================================+==========================+
155 | InstallAllUsers | Perform a system-wide installation. | 0 |
156 +---------------------------+--------------------------------------+--------------------------+
157 | TargetDir | The installation directory | Selected based on |
158 | | | InstallAllUsers |
159 +---------------------------+--------------------------------------+--------------------------+
160 | DefaultAllUsersTargetDir | The default installation directory | :file:`%ProgramFiles%\\\ |
161 | | for all-user installs | Python X.Y` or :file:`\ |
162 | | | %ProgramFiles(x86)%\\\ |
163 | | | Python X.Y` |
164 +---------------------------+--------------------------------------+--------------------------+
165 | DefaultJustForMeTargetDir | The default install directory for | :file:`%LocalAppData%\\\ |
166 | | just-for-me installs | Programs\\Python\\\ |
167 | | | PythonXY` or |
168 | | | :file:`%LocalAppData%\\\ |
169 | | | Programs\\Python\\\ |
170 | | | PythonXY-32` or |
171 | | | :file:`%LocalAppData%\\\ |
172 | | | Programs\\Python\\\ |
173 | | | PythonXY-64` |
174 +---------------------------+--------------------------------------+--------------------------+
175 | DefaultCustomTargetDir | The default custom install directory | (empty) |
176 | | displayed in the UI | |
177 +---------------------------+--------------------------------------+--------------------------+
178 | AssociateFiles | Create file associations if the | 1 |
179 | | launcher is also installed. | |
180 +---------------------------+--------------------------------------+--------------------------+
181 | CompileAll | Compile all ``.py`` files to | 0 |
182 | | ``.pyc``. | |
183 +---------------------------+--------------------------------------+--------------------------+
184 | PrependPath | Prepend install and Scripts | 0 |
185 | | directories to :envvar:`PATH` and | |
186 | | add ``.PY`` to :envvar:`PATHEXT` | |
187 +---------------------------+--------------------------------------+--------------------------+
188 | AppendPath | Append install and Scripts | 0 |
189 | | directories to :envvar:`PATH` and | |
190 | | add ``.PY`` to :envvar:`PATHEXT` | |
191 +---------------------------+--------------------------------------+--------------------------+
192 | Shortcuts | Create shortcuts for the interpreter,| 1 |
193 | | documentation and IDLE if installed. | |
194 +---------------------------+--------------------------------------+--------------------------+
195 | Include_doc | Install Python manual | 1 |
196 +---------------------------+--------------------------------------+--------------------------+
197 | Include_debug | Install debug binaries | 0 |
198 +---------------------------+--------------------------------------+--------------------------+
199 | Include_dev | Install developer headers and | 1 |
200 | | libraries. Omitting this may lead to | |
201 | | an unusable installation. | |
202 +---------------------------+--------------------------------------+--------------------------+
203 | Include_exe | Install :file:`python.exe` and | 1 |
204 | | related files. Omitting this may | |
205 | | lead to an unusable installation. | |
206 +---------------------------+--------------------------------------+--------------------------+
207 | Include_launcher | Install :ref:`launcher`. | 1 |
208 +---------------------------+--------------------------------------+--------------------------+
209 | InstallLauncherAllUsers | Installs the launcher for all | 1 |
210 | | users. Also requires | |
211 | | ``Include_launcher`` to be set to 1 | |
212 +---------------------------+--------------------------------------+--------------------------+
213 | Include_lib | Install standard library and | 1 |
214 | | extension modules. Omitting this may | |
215 | | lead to an unusable installation. | |
216 +---------------------------+--------------------------------------+--------------------------+
217 | Include_pip | Install bundled pip and setuptools | 1 |
218 +---------------------------+--------------------------------------+--------------------------+
219 | Include_symbols | Install debugging symbols (``*.pdb``)| 0 |
220 +---------------------------+--------------------------------------+--------------------------+
221 | Include_tcltk | Install Tcl/Tk support and IDLE | 1 |
222 +---------------------------+--------------------------------------+--------------------------+
223 | Include_test | Install standard library test suite | 1 |
224 +---------------------------+--------------------------------------+--------------------------+
225 | Include_tools | Install utility scripts | 1 |
226 +---------------------------+--------------------------------------+--------------------------+
227 | LauncherOnly | Only installs the launcher. This | 0 |
228 | | will override most other options. | |
229 +---------------------------+--------------------------------------+--------------------------+
230 | SimpleInstall | Disable most install UI | 0 |
231 +---------------------------+--------------------------------------+--------------------------+
232 | SimpleInstallDescription | A custom message to display when the | (empty) |
233 | | simplified install UI is used. | |
234 +---------------------------+--------------------------------------+--------------------------+
235
236 For example, to silently install a default, system-wide Python installation,
237 you could use the following command (from an elevated command prompt)::
238
239 python-3.9.0.exe /quiet InstallAllUsers=1 PrependPath=1 Include_test=0
240
241 To allow users to easily install a personal copy of Python without the test
242 suite, you could provide a shortcut with the following command. This will
243 display a simplified initial page and disallow customization::
244
245 python-3.9.0.exe InstallAllUsers=0 Include_launcher=0 Include_test=0
246 SimpleInstall=1 SimpleInstallDescription="Just for me, no test suite."
247
248 (Note that omitting the launcher also omits file associations, and is only
249 recommended for per-user installs when there is also a system-wide installation
250 that included the launcher.)
251
252 The options listed above can also be provided in a file named ``unattend.xml``
253 alongside the executable. This file specifies a list of options and values.
254 When a value is provided as an attribute, it will be converted to a number if
255 possible. Values provided as element text are always left as strings. This
256 example file sets the same options as the previous example:
257
258 .. code-block:: xml
259
260 <Options>
261 <Option Name="InstallAllUsers" Value="no" />
262 <Option Name="Include_launcher" Value="0" />
263 <Option Name="Include_test" Value="no" />
264 <Option Name="SimpleInstall" Value="yes" />
265 <Option Name="SimpleInstallDescription">Just for me, no test suite</Option>
266 </Options>
267
268 .. _install-layout-option:
269
270 Installing Without Downloading
271 ------------------------------
272
273 As some features of Python are not included in the initial installer download,
274 selecting those features may require an internet connection. To avoid this
275 need, all possible components may be downloaded on-demand to create a complete
276 *layout* that will no longer require an internet connection regardless of the
277 selected features. Note that this download may be bigger than required, but
278 where a large number of installations are going to be performed it is very
279 useful to have a locally cached copy.
280
281 Execute the following command from Command Prompt to download all possible
282 required files. Remember to substitute ``python-3.9.0.exe`` for the actual
283 name of your installer, and to create layouts in their own directories to
284 avoid collisions between files with the same name.
285
286 ::
287
288 python-3.9.0.exe /layout [optional target directory]
289
290 You may also specify the ``/quiet`` option to hide the progress display.
291
292 Modifying an install
293 --------------------
294
295 Once Python has been installed, you can add or remove features through the
296 Programs and Features tool that is part of Windows. Select the Python entry and
297 choose "Uninstall/Change" to open the installer in maintenance mode.
298
299 "Modify" allows you to add or remove features by modifying the checkboxes -
300 unchanged checkboxes will not install or remove anything. Some options cannot be
301 changed in this mode, such as the install directory; to modify these, you will
302 need to remove and then reinstall Python completely.
303
304 "Repair" will verify all the files that should be installed using the current
305 settings and replace any that have been removed or modified.
306
307 "Uninstall" will remove Python entirely, with the exception of the
308 :ref:`launcher`, which has its own entry in Programs and Features.
309
310 .. _install-freethreaded-windows:
311
312 Installing Free-threaded Binaries
313 ---------------------------------
314
315 .. versionadded:: 3.13 (Experimental)
316
317 .. note::
318
319 Everything described in this section is considered experimental,
320 and should be expected to change in future releases.
321
322 To install pre-built binaries with free-threading enabled (see :pep:`703`), you
323 should select "Customize installation". The second page of options includes the
324 "Download free-threaded binaries" checkbox.
325
326 .. image:: win_install_freethreaded.png
327
328 Selecting this option will download and install additional binaries to the same
329 location as the main Python install. The main executable is called
330 ``python3.13t.exe``, and other binaries either receive a ``t`` suffix or a full
331 ABI suffix. Python source files and bundled third-party dependencies are shared
332 with the main install.
333
334 The free-threaded version is registered as a regular Python install with the
335 tag ``3.13t`` (with a ``-32`` or ``-arm64`` suffix as normal for those
336 platforms). This allows tools to discover it, and for the :ref:`launcher` to
337 support ``py.exe -3.13t``. Note that the launcher will interpret ``py.exe -3``
338 (or a ``python3`` shebang) as "the latest 3.x install", which will prefer the
339 free-threaded binaries over the regular ones, while ``py.exe -3.13`` will not.
340 If you use the short style of option, you may prefer to not install the
341 free-threaded binaries at this time.
342
343 To specify the install option at the command line, use
344 ``Include_freethreaded=1``. See :ref:`install-layout-option` for instructions on
345 pre-emptively downloading the additional binaries for offline install. The
346 options to include debug symbols and binaries also apply to the free-threaded
347 builds.
348
349 Free-threaded binaries are also available :ref:`on nuget.org <windows-nuget>`.
350
351 .. _windows-store:
352
353 The Microsoft Store package
354 ===========================
355
356 .. versionadded:: 3.7.2
357
358 The Microsoft Store package is an easily installable Python interpreter that
359 is intended mainly for interactive use, for example, by students.
360
361 To install the package, ensure you have the latest Windows 10 updates and
362 search the Microsoft Store app for "Python |version|". Ensure that the app
363 you select is published by the Python Software Foundation, and install it.
364
365 .. warning::
366 Python will always be available for free on the Microsoft Store. If you
367 are asked to pay for it, you have not selected the correct package.
368
369 After installation, Python may be launched by finding it in Start.
370 Alternatively, it will be available from any Command Prompt or PowerShell
371 session by typing ``python``. Further, pip and IDLE may be used by typing
372 ``pip`` or ``idle``. IDLE can also be found in Start.
373
374 All three commands are also available with version number suffixes, for
375 example, as ``python3.exe`` and ``python3.x.exe`` as well as
376 ``python.exe`` (where ``3.x`` is the specific version you want to launch,
377 such as |version|). Open "Manage App Execution Aliases" through Start to
378 select which version of Python is associated with each command. It is
379 recommended to make sure that ``pip`` and ``idle`` are consistent with
380 whichever version of ``python`` is selected.
381
382 Virtual environments can be created with ``python -m venv`` and activated
383 and used as normal.
384
385 If you have installed another version of Python and added it to your
386 ``PATH`` variable, it will be available as ``python.exe`` rather than the
387 one from the Microsoft Store. To access the new installation, use
388 ``python3.exe`` or ``python3.x.exe``.
389
390 The ``py.exe`` launcher will detect this Python installation, but will prefer
391 installations from the traditional installer.
392
393 To remove Python, open Settings and use Apps and Features, or else find
394 Python in Start and right-click to select Uninstall. Uninstalling will
395 remove all packages you installed directly into this Python installation, but
396 will not remove any virtual environments
397
398 Known issues
399 ------------
400
401 Redirection of local data, registry, and temporary paths
402 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
403
404 Because of restrictions on Microsoft Store apps, Python scripts may not have
405 full write access to shared locations such as :envvar:`TEMP` and the registry.
406 Instead, it will write to a private copy. If your scripts must modify the
407 shared locations, you will need to install the full installer.
408
409 At runtime, Python will use a private copy of well-known Windows folders and the registry.
410 For example, if the environment variable :envvar:`!%APPDATA%` is :file:`c:\\Users\\<user>\\AppData\\`,
411 then when writing to :file:`C:\\Users\\<user>\\AppData\\Local` will write to
412 :file:`C:\\Users\\<user>\\AppData\\Local\\Packages\\PythonSoftwareFoundation.Python.3.8_qbz5n2kfra8p0\\LocalCache\\Local\\`.
413
414 When reading files, Windows will return the file from the private folder, or if that does not exist, the
415 real Windows directory. For example reading :file:`C:\\Windows\\System32` returns the contents of :file:`C:\\Windows\\System32`
416 plus the contents of :file:`C:\\Program Files\\WindowsApps\\package_name\\VFS\\SystemX86`.
417
418 You can find the real path of any existing file using :func:`os.path.realpath`:
419
420 .. code-block:: python
421
422 >>> import os
423 >>> test_file = 'C:\\Users\\example\\AppData\\Local\\test.txt'
424 >>> os.path.realpath(test_file)
425 'C:\\Users\\example\\AppData\\Local\\Packages\\PythonSoftwareFoundation.Python.3.8_qbz5n2kfra8p0\\LocalCache\\Local\\test.txt'
426
427 When writing to the Windows Registry, the following behaviors exist:
428
429 * Reading from ``HKLM\\Software`` is allowed and results are merged with the :file:`registry.dat` file in the package.
430 * Writing to ``HKLM\\Software`` is not allowed if the corresponding key/value exists, i.e. modifying existing keys.
431 * Writing to ``HKLM\\Software`` is allowed as long as a corresponding key/value does not exist in the package
432 and the user has the correct access permissions.
433
434 For more detail on the technical basis for these limitations, please consult
435 Microsoft's documentation on packaged full-trust apps, currently available at
436 `docs.microsoft.com/en-us/windows/msix/desktop/desktop-to-uwp-behind-the-scenes
437 <https://learn.microsoft.com/windows/msix/desktop/desktop-to-uwp-behind-the-scenes>`_
438
439
440 .. _windows-nuget:
441
442 The nuget.org packages
443 ======================
444
445 .. versionadded:: 3.5.2
446
447 The nuget.org package is a reduced size Python environment intended for use on
448 continuous integration and build systems that do not have a system-wide
449 install of Python. While nuget is "the package manager for .NET", it also works
450 perfectly fine for packages containing build-time tools.
451
452 Visit `nuget.org <https://www.nuget.org/>`_ for the most up-to-date information
453 on using nuget. What follows is a summary that is sufficient for Python
454 developers.
455
456 The ``nuget.exe`` command line tool may be downloaded directly from
457 ``https://dist.nuget.org/win-x86-commandline/latest/nuget.exe``, for example,
458 using curl or PowerShell. With the tool, the latest version of Python for
459 64-bit or 32-bit machines is installed using::
460
461 nuget.exe install python -ExcludeVersion -OutputDirectory .
462 nuget.exe install pythonx86 -ExcludeVersion -OutputDirectory .
463
464 To select a particular version, add a ``-Version 3.x.y``. The output directory
465 may be changed from ``.``, and the package will be installed into a
466 subdirectory. By default, the subdirectory is named the same as the package,
467 and without the ``-ExcludeVersion`` option this name will include the specific
468 version installed. Inside the subdirectory is a ``tools`` directory that
469 contains the Python installation:
470
471 .. code-block:: doscon
472
473 # Without -ExcludeVersion
474 > .\python.3.5.2\tools\python.exe -V
475 Python 3.5.2
476
477 # With -ExcludeVersion
478 > .\python\tools\python.exe -V
479 Python 3.5.2
480
481 In general, nuget packages are not upgradeable, and newer versions should be
482 installed side-by-side and referenced using the full path. Alternatively,
483 delete the package directory manually and install it again. Many CI systems
484 will do this automatically if they do not preserve files between builds.
485
486 Alongside the ``tools`` directory is a ``build\native`` directory. This
487 contains a MSBuild properties file ``python.props`` that can be used in a
488 C++ project to reference the Python install. Including the settings will
489 automatically use the headers and import libraries in your build.
490
491 The package information pages on nuget.org are
492 `www.nuget.org/packages/python <https://www.nuget.org/packages/python>`_
493 for the 64-bit version, `www.nuget.org/packages/pythonx86
494 <https://www.nuget.org/packages/pythonx86>`_ for the 32-bit version, and
495 `www.nuget.org/packages/pythonarm64
496 <https://www.nuget.org/packages/pythonarm64>`_ for the ARM64 version
497
498 Free-threaded packages
499 ----------------------
500
501 .. versionadded:: 3.13 (Experimental)
502
503 .. note::
504
505 Everything described in this section is considered experimental,
506 and should be expected to change in future releases.
507
508 Packages containing free-threaded binaries are named
509 `python-freethreaded <https://www.nuget.org/packages/python-freethreaded>`_
510 for the 64-bit version, `pythonx86-freethreaded
511 <https://www.nuget.org/packages/pythonx86-freethreaded>`_ for the 32-bit
512 version, and `pythonarm64-freethreaded
513 <https://www.nuget.org/packages/pythonarm64-freethreaded>`_ for the ARM64
514 version. These packages contain both the ``python3.13t.exe`` and
515 ``python.exe`` entry points, both of which run free threaded.
516
517 .. _windows-embeddable:
518
519 The embeddable package
520 ======================
521
522 .. versionadded:: 3.5
523
524 The embedded distribution is a ZIP file containing a minimal Python environment.
525 It is intended for acting as part of another application, rather than being
526 directly accessed by end-users.
527
528 When extracted, the embedded distribution is (almost) fully isolated from the
529 user's system, including environment variables, system registry settings, and
530 installed packages. The standard library is included as pre-compiled and
531 optimized ``.pyc`` files in a ZIP, and ``python3.dll``, ``python37.dll``,
532 ``python.exe`` and ``pythonw.exe`` are all provided. Tcl/tk (including all
533 dependents, such as Idle), pip and the Python documentation are not included.
534
535 .. note::
536
537 The embedded distribution does not include the `Microsoft C Runtime
538 <https://learn.microsoft.com/cpp/windows/latest-supported-vc-redist#visual-studio-2015-2017-2019-and-2022>`_ and it is
539 the responsibility of the application installer to provide this. The
540 runtime may have already been installed on a user's system previously or
541 automatically via Windows Update, and can be detected by finding
542 ``ucrtbase.dll`` in the system directory.
543
544 Third-party packages should be installed by the application installer alongside
545 the embedded distribution. Using pip to manage dependencies as for a regular
546 Python installation is not supported with this distribution, though with some
547 care it may be possible to include and use pip for automatic updates. In
548 general, third-party packages should be treated as part of the application
549 ("vendoring") so that the developer can ensure compatibility with newer
550 versions before providing updates to users.
551
552 The two recommended use cases for this distribution are described below.
553
554 Python Application
555 ------------------
556
557 An application written in Python does not necessarily require users to be aware
558 of that fact. The embedded distribution may be used in this case to include a
559 private version of Python in an install package. Depending on how transparent it
560 should be (or conversely, how professional it should appear), there are two
561 options.
562
563 Using a specialized executable as a launcher requires some coding, but provides
564 the most transparent experience for users. With a customized launcher, there are
565 no obvious indications that the program is running on Python: icons can be
566 customized, company and version information can be specified, and file
567 associations behave properly. In most cases, a custom launcher should simply be
568 able to call ``Py_Main`` with a hard-coded command line.
569
570 The simpler approach is to provide a batch file or generated shortcut that
571 directly calls the ``python.exe`` or ``pythonw.exe`` with the required
572 command-line arguments. In this case, the application will appear to be Python
573 and not its actual name, and users may have trouble distinguishing it from other
574 running Python processes or file associations.
575
576 With the latter approach, packages should be installed as directories alongside
577 the Python executable to ensure they are available on the path. With the
578 specialized launcher, packages can be located in other locations as there is an
579 opportunity to specify the search path before launching the application.
580
581 Embedding Python
582 ----------------
583
584 Applications written in native code often require some form of scripting
585 language, and the embedded Python distribution can be used for this purpose. In
586 general, the majority of the application is in native code, and some part will
587 either invoke ``python.exe`` or directly use ``python3.dll``. For either case,
588 extracting the embedded distribution to a subdirectory of the application
589 installation is sufficient to provide a loadable Python interpreter.
590
591 As with the application use, packages can be installed to any location as there
592 is an opportunity to specify search paths before initializing the interpreter.
593 Otherwise, there is no fundamental differences between using the embedded
594 distribution and a regular installation.
595
596
597 Alternative bundles
598 ===================
599
600 Besides the standard CPython distribution, there are modified packages including
601 additional functionality. The following is a list of popular versions and their
602 key features:
603
604 `ActivePython <https://www.activestate.com/products/python/>`_
605 Installer with multi-platform compatibility, documentation, PyWin32
606
607 `Anaconda <https://www.anaconda.com/download/>`_
608 Popular scientific modules (such as numpy, scipy and pandas) and the
609 ``conda`` package manager.
610
611 `Enthought Deployment Manager <https://assets.enthought.com/downloads/edm/>`_
612 "The Next Generation Python Environment and Package Manager".
613
614 Previously Enthought provided Canopy, but it `reached end of life in 2016
615 <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>`_.
616
617 `WinPython <https://winpython.github.io/>`_
618 Windows-specific distribution with prebuilt scientific packages and
619 tools for building packages.
620
621 Note that these packages may not include the latest versions of Python or
622 other libraries, and are not maintained or supported by the core Python team.
623
624
625
626 Configuring Python
627 ==================
628
629 To run Python conveniently from a command prompt, you might consider changing
630 some default environment variables in Windows. While the installer provides an
631 option to configure the PATH and PATHEXT variables for you, this is only
632 reliable for a single, system-wide installation. If you regularly use multiple
633 versions of Python, consider using the :ref:`launcher`.
634
635
636 .. _setting-envvars:
637
638 Excursus: Setting environment variables
639 ---------------------------------------
640
641 Windows allows environment variables to be configured permanently at both the
642 User level and the System level, or temporarily in a command prompt.
643
644 To temporarily set environment variables, open Command Prompt and use the
645 :command:`set` command:
646
647 .. code-block:: doscon
648
649 C:\>set PATH=C:\Program Files\Python 3.9;%PATH%
650 C:\>set PYTHONPATH=%PYTHONPATH%;C:\My_python_lib
651 C:\>python
652
653 These changes will apply to any further commands executed in that console, and
654 will be inherited by any applications started from the console.
655
656 Including the variable name within percent signs will expand to the existing
657 value, allowing you to add your new value at either the start or the end.
658 Modifying :envvar:`PATH` by adding the directory containing
659 :program:`python.exe` to the start is a common way to ensure the correct version
660 of Python is launched.
661
662 To permanently modify the default environment variables, click Start and search
663 for 'edit environment variables', or open System properties, :guilabel:`Advanced
664 system settings` and click the :guilabel:`Environment Variables` button.
665 In this dialog, you can add or modify User and System variables. To change
666 System variables, you need non-restricted access to your machine
667 (i.e. Administrator rights).
668
669 .. note::
670
671 Windows will concatenate User variables *after* System variables, which may
672 cause unexpected results when modifying :envvar:`PATH`.
673
674 The :envvar:`PYTHONPATH` variable is used by all versions of Python,
675 so you should not permanently configure it unless the listed paths
676 only include code that is compatible with all of your installed Python
677 versions.
678
679 .. seealso::
680
681 https://learn.microsoft.com/windows/win32/procthread/environment-variables
682 Overview of environment variables on Windows
683
684 https://learn.microsoft.com/windows-server/administration/windows-commands/set_1
685 The ``set`` command, for temporarily modifying environment variables
686
687 https://learn.microsoft.com/windows-server/administration/windows-commands/setx
688 The ``setx`` command, for permanently modifying environment variables
689
690
691 .. _windows-path-mod:
692
693 Finding the Python executable
694 -----------------------------
695
696 .. versionchanged:: 3.5
697
698 Besides using the automatically created start menu entry for the Python
699 interpreter, you might want to start Python in the command prompt. The
700 installer has an option to set that up for you.
701
702 On the first page of the installer, an option labelled "Add Python to PATH"
703 may be selected to have the installer add the install location into the
704 :envvar:`PATH`. The location of the :file:`Scripts\\` folder is also added.
705 This allows you to type :command:`python` to run the interpreter, and
706 :command:`pip` for the package installer. Thus, you can also execute your
707 scripts with command line options, see :ref:`using-on-cmdline` documentation.
708
709 If you don't enable this option at install time, you can always re-run the
710 installer, select Modify, and enable it. Alternatively, you can manually
711 modify the :envvar:`PATH` using the directions in :ref:`setting-envvars`. You
712 need to set your :envvar:`PATH` environment variable to include the directory
713 of your Python installation, delimited by a semicolon from other entries. An
714 example variable could look like this (assuming the first two entries already
715 existed)::
716
717 C:\WINDOWS\system32;C:\WINDOWS;C:\Program Files\Python 3.9
718
719 .. _win-utf8-mode:
720
721 UTF-8 mode
722 ==========
723
724 .. versionadded:: 3.7
725
726 Windows still uses legacy encodings for the system encoding (the ANSI Code
727 Page). Python uses it for the default encoding of text files (e.g.
728 :func:`locale.getencoding`).
729
730 This may cause issues because UTF-8 is widely used on the internet
731 and most Unix systems, including WSL (Windows Subsystem for Linux).
732
733 You can use the :ref:`Python UTF-8 Mode <utf8-mode>` to change the default text
734 encoding to UTF-8. You can enable the :ref:`Python UTF-8 Mode <utf8-mode>` via
735 the ``-X utf8`` command line option, or the ``PYTHONUTF8=1`` environment
736 variable. See :envvar:`PYTHONUTF8` for enabling UTF-8 mode, and
737 :ref:`setting-envvars` for how to modify environment variables.
738
739 When the :ref:`Python UTF-8 Mode <utf8-mode>` is enabled, you can still use the
740 system encoding (the ANSI Code Page) via the "mbcs" codec.
741
742 Note that adding ``PYTHONUTF8=1`` to the default environment variables
743 will affect all Python 3.7+ applications on your system.
744 If you have any Python 3.7+ applications which rely on the legacy
745 system encoding, it is recommended to set the environment variable
746 temporarily or use the ``-X utf8`` command line option.
747
748 .. note::
749 Even when UTF-8 mode is disabled, Python uses UTF-8 by default
750 on Windows for:
751
752 * Console I/O including standard I/O (see :pep:`528` for details).
753 * The :term:`filesystem encoding <filesystem encoding and error handler>`
754 (see :pep:`529` for details).
755
756
757 .. _launcher:
758
759 Python Launcher for Windows
760 ===========================
761
762 .. versionadded:: 3.3
763
764 The Python launcher for Windows is a utility which aids in locating and
765 executing of different Python versions. It allows scripts (or the
766 command-line) to indicate a preference for a specific Python version, and
767 will locate and execute that version.
768
769 Unlike the :envvar:`PATH` variable, the launcher will correctly select the most
770 appropriate version of Python. It will prefer per-user installations over
771 system-wide ones, and orders by language version rather than using the most
772 recently installed version.
773
774 The launcher was originally specified in :pep:`397`.
775
776 Getting started
777 ---------------
778
779 From the command-line
780 ^^^^^^^^^^^^^^^^^^^^^
781
782 .. versionchanged:: 3.6
783
784 System-wide installations of Python 3.3 and later will put the launcher on your
785 :envvar:`PATH`. The launcher is compatible with all available versions of
786 Python, so it does not matter which version is installed. To check that the
787 launcher is available, execute the following command in Command Prompt::
788
789 py
790
791 You should find that the latest version of Python you have installed is
792 started - it can be exited as normal, and any additional command-line
793 arguments specified will be sent directly to Python.
794
795 If you have multiple versions of Python installed (e.g., 3.7 and |version|) you
796 will have noticed that Python |version| was started - to launch Python 3.7, try
797 the command::
798
799 py -3.7
800
801 If you want the latest version of Python 2 you have installed, try the
802 command::
803
804 py -2
805
806 If you see the following error, you do not have the launcher installed::
807
808 'py' is not recognized as an internal or external command,
809 operable program or batch file.
810
811 The command::
812
813 py --list
814
815 displays the currently installed version(s) of Python.
816
817 The ``-x.y`` argument is the short form of the ``-V:Company/Tag`` argument,
818 which allows selecting a specific Python runtime, including those that may have
819 come from somewhere other than python.org. Any runtime registered by following
820 :pep:`514` will be discoverable. The ``--list`` command lists all available
821 runtimes using the ``-V:`` format.
822
823 When using the ``-V:`` argument, specifying the Company will limit selection to
824 runtimes from that provider, while specifying only the Tag will select from all
825 providers. Note that omitting the slash implies a tag::
826
827 # Select any '3.*' tagged runtime
828 py -V:3
829
830 # Select any 'PythonCore' released runtime
831 py -V:PythonCore/
832
833 # Select PythonCore's latest Python 3 runtime
834 py -V:PythonCore/3
835
836 The short form of the argument (``-3``) only ever selects from core Python
837 releases, and not other distributions. However, the longer form (``-V:3``) will
838 select from any.
839
840 The Company is matched on the full string, case-insensitive. The Tag is matched
841 on either the full string, or a prefix, provided the next character is a dot or a
842 hyphen. This allows ``-V:3.1`` to match ``3.1-32``, but not ``3.10``. Tags are
843 sorted using numerical ordering (``3.10`` is newer than ``3.1``), but are
844 compared using text (``-V:3.01`` does not match ``3.1``).
845
846
847 Virtual environments
848 ^^^^^^^^^^^^^^^^^^^^
849
850 .. versionadded:: 3.5
851
852 If the launcher is run with no explicit Python version specification, and a
853 virtual environment (created with the standard library :mod:`venv` module or
854 the external ``virtualenv`` tool) active, the launcher will run the virtual
855 environment's interpreter rather than the global one. To run the global
856 interpreter, either deactivate the virtual environment, or explicitly specify
857 the global Python version.
858
859 From a script
860 ^^^^^^^^^^^^^
861
862 Let's create a test Python script - create a file called ``hello.py`` with the
863 following contents
864
865 .. code-block:: python
866
867 #! python
868 import sys
869 sys.stdout.write("hello from Python %s\n" % (sys.version,))
870
871 From the directory in which hello.py lives, execute the command::
872
873 py hello.py
874
875 You should notice the version number of your latest Python 2.x installation
876 is printed. Now try changing the first line to be:
877
878 .. code-block:: python
879
880 #! python3
881
882 Re-executing the command should now print the latest Python 3.x information.
883 As with the above command-line examples, you can specify a more explicit
884 version qualifier. Assuming you have Python 3.7 installed, try changing
885 the first line to ``#! python3.7`` and you should find the 3.7
886 version information printed.
887
888 Note that unlike interactive use, a bare "python" will use the latest
889 version of Python 2.x that you have installed. This is for backward
890 compatibility and for compatibility with Unix, where the command ``python``
891 typically refers to Python 2.
892
893 From file associations
894 ^^^^^^^^^^^^^^^^^^^^^^
895
896 The launcher should have been associated with Python files (i.e. ``.py``,
897 ``.pyw``, ``.pyc`` files) when it was installed. This means that
898 when you double-click on one of these files from Windows explorer the launcher
899 will be used, and therefore you can use the same facilities described above to
900 have the script specify the version which should be used.
901
902 The key benefit of this is that a single launcher can support multiple Python
903 versions at the same time depending on the contents of the first line.
904
905 Shebang Lines
906 -------------
907
908 If the first line of a script file starts with ``#!``, it is known as a
909 "shebang" line. Linux and other Unix like operating systems have native
910 support for such lines and they are commonly used on such systems to indicate
911 how a script should be executed. This launcher allows the same facilities to
912 be used with Python scripts on Windows and the examples above demonstrate their
913 use.
914
915 To allow shebang lines in Python scripts to be portable between Unix and
916 Windows, this launcher supports a number of 'virtual' commands to specify
917 which interpreter to use. The supported virtual commands are:
918
919 * ``/usr/bin/env``
920 * ``/usr/bin/python``
921 * ``/usr/local/bin/python``
922 * ``python``
923
924 For example, if the first line of your script starts with
925
926 .. code-block:: sh
927
928 #! /usr/bin/python
929
930 The default Python or an active virtual environment will be located and used.
931 As many Python scripts written to work on Unix will already have this line,
932 you should find these scripts can be used by the launcher without modification.
933 If you are writing a new script on Windows which you hope will be useful on
934 Unix, you should use one of the shebang lines starting with ``/usr``.
935
936 Any of the above virtual commands can be suffixed with an explicit version
937 (either just the major version, or the major and minor version).
938 Furthermore the 32-bit version can be requested by adding "-32" after the
939 minor version. I.e. ``/usr/bin/python3.7-32`` will request usage of the
940 32-bit Python 3.7. If a virtual environment is active, the version will be
941 ignored and the environment will be used.
942
943 .. versionadded:: 3.7
944
945 Beginning with python launcher 3.7 it is possible to request 64-bit version
946 by the "-64" suffix. Furthermore it is possible to specify a major and
947 architecture without minor (i.e. ``/usr/bin/python3-64``).
948
949 .. versionchanged:: 3.11
950
951 The "-64" suffix is deprecated, and now implies "any architecture that is
952 not provably i386/32-bit". To request a specific environment, use the new
953 :samp:`-V:{TAG}` argument with the complete tag.
954
955 .. versionchanged:: 3.13
956
957 Virtual commands referencing ``python`` now prefer an active virtual
958 environment rather than searching :envvar:`PATH`. This handles cases where
959 the shebang specifies ``/usr/bin/env python3`` but :file:`python3.exe` is
960 not present in the active environment.
961
962 The ``/usr/bin/env`` form of shebang line has one further special property.
963 Before looking for installed Python interpreters, this form will search the
964 executable :envvar:`PATH` for a Python executable matching the name provided
965 as the first argument. This corresponds to the behaviour of the Unix ``env``
966 program, which performs a :envvar:`PATH` search.
967 If an executable matching the first argument after the ``env`` command cannot
968 be found, but the argument starts with ``python``, it will be handled as
969 described for the other virtual commands.
970 The environment variable :envvar:`!PYLAUNCHER_NO_SEARCH_PATH` may be set
971 (to any value) to skip this search of :envvar:`PATH`.
972
973 Shebang lines that do not match any of these patterns are looked up in the
974 ``[commands]`` section of the launcher's :ref:`.INI file <launcher-ini>`.
975 This may be used to handle certain commands in a way that makes sense for your
976 system. The name of the command must be a single argument (no spaces in the
977 shebang executable), and the value substituted is the full path to the
978 executable (additional arguments specified in the .INI will be quoted as part
979 of the filename).
980
981 .. code-block:: ini
982
983 [commands]
984 /bin/xpython=C:\Program Files\XPython\python.exe
985
986 Any commands not found in the .INI file are treated as **Windows** executable
987 paths that are absolute or relative to the directory containing the script file.
988 This is a convenience for Windows-only scripts, such as those generated by an
989 installer, since the behavior is not compatible with Unix-style shells.
990 These paths may be quoted, and may include multiple arguments, after which the
991 path to the script and any additional arguments will be appended.
992
993
994 Arguments in shebang lines
995 --------------------------
996
997 The shebang lines can also specify additional options to be passed to the
998 Python interpreter. For example, if you have a shebang line:
999
1000 .. code-block:: sh
1001
1002 #! /usr/bin/python -v
1003
1004 Then Python will be started with the ``-v`` option
1005
1006 Customization
1007 -------------
1008
1009 .. _launcher-ini:
1010
1011 Customization via INI files
1012 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
1013
1014 Two .ini files will be searched by the launcher - ``py.ini`` in the current
1015 user's application data directory (``%LOCALAPPDATA%`` or ``$env:LocalAppData``)
1016 and ``py.ini`` in the same directory as the launcher. The same .ini files are
1017 used for both the 'console' version of the launcher (i.e. py.exe) and for the
1018 'windows' version (i.e. pyw.exe).
1019
1020 Customization specified in the "application directory" will have precedence over
1021 the one next to the executable, so a user, who may not have write access to the
1022 .ini file next to the launcher, can override commands in that global .ini file.
1023
1024 Customizing default Python versions
1025 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1026
1027 In some cases, a version qualifier can be included in a command to dictate
1028 which version of Python will be used by the command. A version qualifier
1029 starts with a major version number and can optionally be followed by a period
1030 ('.') and a minor version specifier. Furthermore it is possible to specify
1031 if a 32 or 64 bit implementation shall be requested by adding "-32" or "-64".
1032
1033 For example, a shebang line of ``#!python`` has no version qualifier, while
1034 ``#!python3`` has a version qualifier which specifies only a major version.
1035
1036 If no version qualifiers are found in a command, the environment
1037 variable :envvar:`!PY_PYTHON` can be set to specify the default version
1038 qualifier. If it is not set, the default is "3". The variable can
1039 specify any value that may be passed on the command line, such as "3",
1040 "3.7", "3.7-32" or "3.7-64". (Note that the "-64" option is only
1041 available with the launcher included with Python 3.7 or newer.)
1042
1043 If no minor version qualifiers are found, the environment variable
1044 ``PY_PYTHON{major}`` (where ``{major}`` is the current major version qualifier
1045 as determined above) can be set to specify the full version. If no such option
1046 is found, the launcher will enumerate the installed Python versions and use
1047 the latest minor release found for the major version, which is likely,
1048 although not guaranteed, to be the most recently installed version in that
1049 family.
1050
1051 On 64-bit Windows with both 32-bit and 64-bit implementations of the same
1052 (major.minor) Python version installed, the 64-bit version will always be
1053 preferred. This will be true for both 32-bit and 64-bit implementations of the
1054 launcher - a 32-bit launcher will prefer to execute a 64-bit Python installation
1055 of the specified version if available. This is so the behavior of the launcher
1056 can be predicted knowing only what versions are installed on the PC and
1057 without regard to the order in which they were installed (i.e., without knowing
1058 whether a 32 or 64-bit version of Python and corresponding launcher was
1059 installed last). As noted above, an optional "-32" or "-64" suffix can be
1060 used on a version specifier to change this behaviour.
1061
1062 Examples:
1063
1064 * If no relevant options are set, the commands ``python`` and
1065 ``python2`` will use the latest Python 2.x version installed and
1066 the command ``python3`` will use the latest Python 3.x installed.
1067
1068 * The command ``python3.7`` will not consult any
1069 options at all as the versions are fully specified.
1070
1071 * If ``PY_PYTHON=3``, the commands ``python`` and ``python3`` will both use
1072 the latest installed Python 3 version.
1073
1074 * If ``PY_PYTHON=3.7-32``, the command ``python`` will use the 32-bit
1075 implementation of 3.7 whereas the command ``python3`` will use the latest
1076 installed Python (PY_PYTHON was not considered at all as a major
1077 version was specified.)
1078
1079 * If ``PY_PYTHON=3`` and ``PY_PYTHON3=3.7``, the commands
1080 ``python`` and ``python3`` will both use specifically 3.7
1081
1082 In addition to environment variables, the same settings can be configured
1083 in the .INI file used by the launcher. The section in the INI file is
1084 called ``[defaults]`` and the key name will be the same as the
1085 environment variables without the leading ``PY_`` prefix (and note that
1086 the key names in the INI file are case insensitive.) The contents of
1087 an environment variable will override things specified in the INI file.
1088
1089 For example:
1090
1091 * Setting ``PY_PYTHON=3.7`` is equivalent to the INI file containing:
1092
1093 .. code-block:: ini
1094
1095 [defaults]
1096 python=3.7
1097
1098 * Setting ``PY_PYTHON=3`` and ``PY_PYTHON3=3.7`` is equivalent to the INI file
1099 containing:
1100
1101 .. code-block:: ini
1102
1103 [defaults]
1104 python=3
1105 python3=3.7
1106
1107 Diagnostics
1108 -----------
1109
1110 If an environment variable :envvar:`!PYLAUNCHER_DEBUG` is set (to any value), the
1111 launcher will print diagnostic information to stderr (i.e. to the console).
1112 While this information manages to be simultaneously verbose *and* terse, it
1113 should allow you to see what versions of Python were located, why a
1114 particular version was chosen and the exact command-line used to execute the
1115 target Python. It is primarily intended for testing and debugging.
1116
1117 Dry Run
1118 -------
1119
1120 If an environment variable :envvar:`!PYLAUNCHER_DRYRUN` is set (to any value),
1121 the launcher will output the command it would have run, but will not actually
1122 launch Python. This may be useful for tools that want to use the launcher to
1123 detect and then launch Python directly. Note that the command written to
1124 standard output is always encoded using UTF-8, and may not render correctly in
1125 the console.
1126
1127 Install on demand
1128 -----------------
1129
1130 If an environment variable :envvar:`!PYLAUNCHER_ALLOW_INSTALL` is set (to any
1131 value), and the requested Python version is not installed but is available on
1132 the Microsoft Store, the launcher will attempt to install it. This may require
1133 user interaction to complete, and you may need to run the command again.
1134
1135 An additional :envvar:`!PYLAUNCHER_ALWAYS_INSTALL` variable causes the launcher
1136 to always try to install Python, even if it is detected. This is mainly intended
1137 for testing (and should be used with :envvar:`!PYLAUNCHER_DRYRUN`).
1138
1139 Return codes
1140 ------------
1141
1142 The following exit codes may be returned by the Python launcher. Unfortunately,
1143 there is no way to distinguish these from the exit code of Python itself.
1144
1145 The names of codes are as used in the sources, and are only for reference. There
1146 is no way to access or resolve them apart from reading this page. Entries are
1147 listed in alphabetical order of names.
1148
1149 +-------------------+-------+-----------------------------------------------+
1150 | Name | Value | Description |
1151 +===================+=======+===============================================+
1152 | RC_BAD_VENV_CFG | 107 | A :file:`pyvenv.cfg` was found but is corrupt.|
1153 +-------------------+-------+-----------------------------------------------+
1154 | RC_CREATE_PROCESS | 101 | Failed to launch Python. |
1155 +-------------------+-------+-----------------------------------------------+
1156 | RC_INSTALLING | 111 | An install was started, but the command will |
1157 | | | need to be re-run after it completes. |
1158 +-------------------+-------+-----------------------------------------------+
1159 | RC_INTERNAL_ERROR | 109 | Unexpected error. Please report a bug. |
1160 +-------------------+-------+-----------------------------------------------+
1161 | RC_NO_COMMANDLINE | 108 | Unable to obtain command line from the |
1162 | | | operating system. |
1163 +-------------------+-------+-----------------------------------------------+
1164 | RC_NO_PYTHON | 103 | Unable to locate the requested version. |
1165 +-------------------+-------+-----------------------------------------------+
1166 | RC_NO_VENV_CFG | 106 | A :file:`pyvenv.cfg` was required but not |
1167 | | | found. |
1168 +-------------------+-------+-----------------------------------------------+
1169
1170
1171 .. _windows_finding_modules:
1172
1173 Finding modules
1174 ===============
1175
1176 These notes supplement the description at :ref:`sys-path-init` with
1177 detailed Windows notes.
1178
1179 When no ``._pth`` file is found, this is how :data:`sys.path` is populated on
1180 Windows:
1181
1182 * An empty entry is added at the start, which corresponds to the current
1183 directory.
1184
1185 * If the environment variable :envvar:`PYTHONPATH` exists, as described in
1186 :ref:`using-on-envvars`, its entries are added next. Note that on Windows,
1187 paths in this variable must be separated by semicolons, to distinguish them
1188 from the colon used in drive identifiers (``C:\`` etc.).
1189
1190 * Additional "application paths" can be added in the registry as subkeys of
1191 :samp:`\\SOFTWARE\\Python\\PythonCore\\{version}\\PythonPath` under both the
1192 ``HKEY_CURRENT_USER`` and ``HKEY_LOCAL_MACHINE`` hives. Subkeys which have
1193 semicolon-delimited path strings as their default value will cause each path
1194 to be added to :data:`sys.path`. (Note that all known installers only use
1195 HKLM, so HKCU is typically empty.)
1196
1197 * If the environment variable :envvar:`PYTHONHOME` is set, it is assumed as
1198 "Python Home". Otherwise, the path of the main Python executable is used to
1199 locate a "landmark file" (either ``Lib\os.py`` or ``pythonXY.zip``) to deduce
1200 the "Python Home". If a Python home is found, the relevant sub-directories
1201 added to :data:`sys.path` (``Lib``, ``plat-win``, etc) are based on that
1202 folder. Otherwise, the core Python path is constructed from the PythonPath
1203 stored in the registry.
1204
1205 * If the Python Home cannot be located, no :envvar:`PYTHONPATH` is specified in
1206 the environment, and no registry entries can be found, a default path with
1207 relative entries is used (e.g. ``.\Lib;.\plat-win``, etc).
1208
1209 If a ``pyvenv.cfg`` file is found alongside the main executable or in the
1210 directory one level above the executable, the following variations apply:
1211
1212 * If ``home`` is an absolute path and :envvar:`PYTHONHOME` is not set, this
1213 path is used instead of the path to the main executable when deducing the
1214 home location.
1215
1216 The end result of all this is:
1217
1218 * When running :file:`python.exe`, or any other .exe in the main Python
1219 directory (either an installed version, or directly from the PCbuild
1220 directory), the core path is deduced, and the core paths in the registry are
1221 ignored. Other "application paths" in the registry are always read.
1222
1223 * When Python is hosted in another .exe (different directory, embedded via COM,
1224 etc), the "Python Home" will not be deduced, so the core path from the
1225 registry is used. Other "application paths" in the registry are always read.
1226
1227 * If Python can't find its home and there are no registry value (frozen .exe,
1228 some very strange installation setup) you get a path with some default, but
1229 relative, paths.
1230
1231 For those who want to bundle Python into their application or distribution, the
1232 following advice will prevent conflicts with other installations:
1233
1234 * Include a ``._pth`` file alongside your executable containing the
1235 directories to include. This will ignore paths listed in the registry and
1236 environment variables, and also ignore :mod:`site` unless ``import site`` is
1237 listed.
1238
1239 * If you are loading :file:`python3.dll` or :file:`python37.dll` in your own
1240 executable, explicitly set :c:member:`PyConfig.module_search_paths` before
1241 :c:func:`Py_InitializeFromConfig`.
1242
1243 * Clear and/or overwrite :envvar:`PYTHONPATH` and set :envvar:`PYTHONHOME`
1244 before launching :file:`python.exe` from your application.
1245
1246 * If you cannot use the previous suggestions (for example, you are a
1247 distribution that allows people to run :file:`python.exe` directly), ensure
1248 that the landmark file (:file:`Lib\\os.py`) exists in your install directory.
1249 (Note that it will not be detected inside a ZIP file, but a correctly named
1250 ZIP file will be detected instead.)
1251
1252 These will ensure that the files in a system-wide installation will not take
1253 precedence over the copy of the standard library bundled with your application.
1254 Otherwise, your users may experience problems using your application. Note that
1255 the first suggestion is the best, as the others may still be susceptible to
1256 non-standard paths in the registry and user site-packages.
1257
1258 .. versionchanged:: 3.6
1259
1260 Add ``._pth`` file support and removes ``applocal`` option from
1261 ``pyvenv.cfg``.
1262
1263 .. versionchanged:: 3.6
1264
1265 Add :file:`python{XX}.zip` as a potential landmark when directly adjacent
1266 to the executable.
1267
1268 .. deprecated:: 3.6
1269
1270 Modules specified in the registry under ``Modules`` (not ``PythonPath``)
1271 may be imported by :class:`importlib.machinery.WindowsRegistryFinder`.
1272 This finder is enabled on Windows in 3.6.0 and earlier, but may need to
1273 be explicitly added to :data:`sys.meta_path` in the future.
1274
1275 Additional modules
1276 ==================
1277
1278 Even though Python aims to be portable among all platforms, there are features
1279 that are unique to Windows. A couple of modules, both in the standard library
1280 and external, and snippets exist to use these features.
1281
1282 The Windows-specific standard modules are documented in
1283 :ref:`mswin-specific-services`.
1284
1285 PyWin32
1286 -------
1287
1288 The :pypi:`PyWin32` module by Mark Hammond
1289 is a collection of modules for advanced Windows-specific support. This includes
1290 utilities for:
1291
1292 * `Component Object Model
1293 <https://learn.microsoft.com/windows/win32/com/component-object-model--com--portal>`_
1294 (COM)
1295 * Win32 API calls
1296 * Registry
1297 * Event log
1298 * `Microsoft Foundation Classes
1299 <https://learn.microsoft.com/cpp/mfc/mfc-desktop-applications>`_
1300 (MFC) user interfaces
1301
1302 `PythonWin <https://web.archive.org/web/20060524042422/
1303 https://www.python.org/windows/pythonwin/>`_ is a sample MFC application
1304 shipped with PyWin32. It is an embeddable IDE with a built-in debugger.
1305
1306 .. seealso::
1307
1308 `Win32 How Do I...? <https://timgolden.me.uk/python/win32_how_do_i.html>`_
1309 by Tim Golden
1310
1311 `Python and COM <https://www.boddie.org.uk/python/COM.html>`_
1312 by David and Paul Boddie
1313
1314
1315 cx_Freeze
1316 ---------
1317
1318 `cx_Freeze <https://cx-freeze.readthedocs.io/en/latest/>`_
1319 wraps Python scripts into executable Windows programs
1320 (:file:`{*}.exe` files). When you have done this, you can distribute your
1321 application without requiring your users to install Python.
1322
1323
1324 Compiling Python on Windows
1325 ===========================
1326
1327 If you want to compile CPython yourself, first thing you should do is get the
1328 `source <https://www.python.org/downloads/source/>`_. You can download either the
1329 latest release's source or just grab a fresh `checkout
1330 <https://devguide.python.org/setup/#get-the-source-code>`_.
1331
1332 The source tree contains a build solution and project files for Microsoft
1333 Visual Studio, which is the compiler used to build the official Python
1334 releases. These files are in the :file:`PCbuild` directory.
1335
1336 Check :file:`PCbuild/readme.txt` for general information on the build process.
1337
1338 For extension modules, consult :ref:`building-on-windows`.
1339
1340
1341 Other Platforms
1342 ===============
1343
1344 With ongoing development of Python, some platforms that used to be supported
1345 earlier are no longer supported (due to the lack of users or developers).
1346 Check :pep:`11` for details on all unsupported platforms.
1347
1348 * `Windows CE <https://pythonce.sourceforge.net/>`_ is
1349 `no longer supported <https://github.com/python/cpython/issues/71542>`__
1350 since Python 3 (if it ever was).
1351 * The `Cygwin <https://cygwin.com/>`_ installer offers to install the
1352 `Python interpreter <https://cygwin.com/packages/summary/python3.html>`__
1353 as well
1354
1355 See `Python for Windows <https://www.python.org/downloads/windows/>`_
1356 for detailed information about platforms with pre-compiled installers.