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