| 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. |