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