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