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