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