1.. highlightlang:: none 2 3.. _using-on-windows: 4 5************************* 6 Using Python on Windows 7************************* 8 9.. sectionauthor:: Robert Lehmann <lehmannro@gmail.com> 10 11This document aims to give an overview of Windows-specific behaviour you should 12know about when using Python on Microsoft Windows. 13 14 15Installing Python 16================= 17 18Unlike most Unix systems and services, Windows does not require Python natively 19and thus does not pre-install a version of Python. However, the CPython team 20has compiled Windows installers (MSI packages) with every `release 21<https://www.python.org/download/releases/>`_ for many years. 22 23With ongoing development of Python, some platforms that used to be supported 24earlier are no longer supported (due to the lack of users or developers). 25Check :pep:`11` for details on all unsupported platforms. 26 27* DOS and Windows 3.x are deprecated since Python 2.0 and code specific to these 28 systems was removed in Python 2.1. 29* Up to 2.5, Python was still compatible with Windows 95, 98 and ME (but already 30 raised a deprecation warning on installation). For Python 2.6 (and all 31 following releases), this support was dropped and new releases are just 32 expected to work on the Windows NT family. 33* `Windows CE <http://pythonce.sourceforge.net/>`_ is still supported. 34* The `Cygwin <https://cygwin.com/>`_ installer offers to install the Python 35 interpreter as well (cf. `Cygwin package source 36 <ftp://ftp.uni-erlangen.de/pub/pc/gnuwin32/cygwin/mirrors/cygnus/ 37 release/python>`_, `Maintainer releases 38 <http://www.tishler.net/jason/software/python/>`_) 39 40See `Python for Windows (and DOS) <https://www.python.org/download/windows/>`_ 41for detailed information about platforms with precompiled installers. 42 43.. seealso:: 44 45 `Python on XP <http://dooling.com/index.php/2006/03/14/python-on-xp-7-minutes-to-hello-world/>`_ 46 "7 Minutes to "Hello World!"" 47 by Richard Dooling, 2006 48 49 `Installing on Windows <http://www.diveintopython.net/installing_python/windows.html>`_ 50 in "`Dive into Python: Python from novice to pro 51 <http://www.diveintopython.net/>`_" 52 by Mark Pilgrim, 2004, 53 ISBN 1-59059-356-1 54 55 `For Windows users <http://python.swaroopch.com/installation.html#installation-on-windows>`_ 56 in "Installing Python" 57 in "`A Byte of Python <http://python.swaroopch.com/>`_" 58 by Swaroop C H, 2003 59 60 61Alternative bundles 62=================== 63 64Besides the standard CPython distribution, there are modified packages including 65additional functionality. The following is a list of popular versions and their 66key features: 67 68`ActivePython <https://www.activestate.com/activepython/>`_ 69 Installer with multi-platform compatibility, documentation, PyWin32 70 71`Enthought Python Distribution <https://www.enthought.com/products/epd/>`_ 72 Popular modules (such as PyWin32) with their respective documentation, tool 73 suite for building extensible Python applications 74 75Notice that these packages are likely to install *older* versions of Python. 76 77 78 79Configuring Python 80================== 81 82In order to run Python flawlessly, you might have to change certain environment 83settings in Windows. 84 85 86.. _setting-envvars: 87 88Excursus: Setting environment variables 89--------------------------------------- 90 91Windows has a built-in dialog for changing environment variables (following 92guide applies to XP classical view): Right-click the icon for your machine 93(usually located on your Desktop and called "My Computer") and choose 94:menuselection:`Properties` there. Then, open the :guilabel:`Advanced` tab 95and click the :guilabel:`Environment Variables` button. 96 97In short, your path is: 98 99 :menuselection:`My Computer 100 --> Properties 101 --> Advanced 102 --> Environment Variables` 103 104In this dialog, you can add or modify User and System variables. To change 105System variables, you need non-restricted access to your machine 106(i.e. Administrator rights). 107 108Another way of adding variables to your environment is using the :command:`set` 109command:: 110 111 set PYTHONPATH=%PYTHONPATH%;C:\My_python_lib 112 113To make this setting permanent, you could add the corresponding command line to 114your :file:`autoexec.bat`. :program:`msconfig` is a graphical interface to this 115file. 116 117Viewing environment variables can also be done more straight-forward: The 118command prompt will expand strings wrapped into percent signs automatically:: 119 120 echo %PATH% 121 122Consult :command:`set /?` for details on this behaviour. 123 124.. seealso:: 125 126 https://support.microsoft.com/kb/100843 127 Environment variables in Windows NT 128 129 https://support.microsoft.com/kb/310519 130 How To Manage Environment Variables in Windows XP 131 132 https://www.chem.gla.ac.uk/~louis/software/faq/q1.html 133 Setting Environment variables, Louis J. Farrugia 134 135 136Finding the Python executable 137----------------------------- 138 139Besides using the automatically created start menu entry for the Python 140interpreter, you might want to start Python in the DOS prompt. To make this 141work, you need to set your :envvar:`%PATH%` environment variable to include the 142directory of your Python distribution, delimited by a semicolon from other 143entries. An example variable could look like this (assuming the first two 144entries are Windows' default):: 145 146 C:\WINDOWS\system32;C:\WINDOWS;C:\Python25 147 148Typing :command:`python` on your command prompt will now fire up the Python 149interpreter. Thus, you can also execute your scripts with command line options, 150see :ref:`using-on-cmdline` documentation. 151 152 153Finding modules 154--------------- 155 156Python usually stores its library (and thereby your site-packages folder) in the 157installation directory. So, if you had installed Python to 158:file:`C:\\Python\\`, the default library would reside in 159:file:`C:\\Python\\Lib\\` and third-party modules should be stored in 160:file:`C:\\Python\\Lib\\site-packages\\`. 161 162This is how :data:`sys.path` is populated on Windows: 163 164* An empty entry is added at the start, which corresponds to the current 165 directory. 166 167* If the environment variable :envvar:`PYTHONPATH` exists, as described in 168 :ref:`using-on-envvars`, its entries are added next. Note that on Windows, 169 paths in this variable must be separated by semicolons, to distinguish them 170 from the colon used in drive identifiers (``C:\`` etc.). 171 172* Additional "application paths" can be added in the registry as subkeys of 173 :samp:`\\SOFTWARE\\Python\\PythonCore\\{version}\\PythonPath` under both the 174 ``HKEY_CURRENT_USER`` and ``HKEY_LOCAL_MACHINE`` hives. Subkeys which have 175 semicolon-delimited path strings as their default value will cause each path 176 to be added to :data:`sys.path`. (Note that all known installers only use 177 HKLM, so HKCU is typically empty.) 178 179* If the environment variable :envvar:`PYTHONHOME` is set, it is assumed as 180 "Python Home". Otherwise, the path of the main Python executable is used to 181 locate a "landmark file" (``Lib\os.py``) to deduce the "Python Home". If a 182 Python home is found, the relevant sub-directories added to :data:`sys.path` 183 (``Lib``, ``plat-win``, etc) are based on that folder. Otherwise, the core 184 Python path is constructed from the PythonPath stored in the registry. 185 186* If the Python Home cannot be located, no :envvar:`PYTHONPATH` is specified in 187 the environment, and no registry entries can be found, a default path with 188 relative entries is used (e.g. ``.\Lib;.\plat-win``, etc). 189 190The end result of all this is: 191 192* When running :file:`python.exe`, or any other .exe in the main Python 193 directory (either an installed version, or directly from the PCbuild 194 directory), the core path is deduced, and the core paths in the registry are 195 ignored. Other "application paths" in the registry are always read. 196 197* When Python is hosted in another .exe (different directory, embedded via COM, 198 etc), the "Python Home" will not be deduced, so the core path from the 199 registry is used. Other "application paths" in the registry are always read. 200 201* If Python can't find its home and there is no registry (eg, frozen .exe, some 202 very strange installation setup) you get a path with some default, but 203 relative, paths. 204 205 206Executing scripts 207----------------- 208 209Python scripts (files with the extension ``.py``) will be executed by 210:program:`python.exe` by default. This executable opens a terminal, which stays 211open even if the program uses a GUI. If you do not want this to happen, use the 212extension ``.pyw`` which will cause the script to be executed by 213:program:`pythonw.exe` by default (both executables are located in the top-level 214of your Python installation directory). This suppresses the terminal window on 215startup. 216 217You can also make all ``.py`` scripts execute with :program:`pythonw.exe`, 218setting this through the usual facilities, for example (might require 219administrative rights): 220 221#. Launch a command prompt. 222#. Associate the correct file group with ``.py`` scripts:: 223 224 assoc .py=Python.File 225 226#. Redirect all Python files to the new executable:: 227 228 ftype Python.File=C:\Path\to\pythonw.exe "%1" %* 229 230 231Additional modules 232================== 233 234Even though Python aims to be portable among all platforms, there are features 235that are unique to Windows. A couple of modules, both in the standard library 236and external, and snippets exist to use these features. 237 238The Windows-specific standard modules are documented in 239:ref:`mswin-specific-services`. 240 241 242PyWin32 243------- 244 245The `PyWin32 <https://pypi.org/project/pywin32>`_ module by Mark Hammond 246is a collection of modules for advanced Windows-specific support. This includes 247utilities for: 248 249* `Component Object Model <https://www.microsoft.com/com/>`_ (COM) 250* Win32 API calls 251* Registry 252* Event log 253* `Microsoft Foundation Classes <https://msdn.microsoft.com/en-us/library/fe1cf721%28VS.80%29.aspx>`_ (MFC) 254 user interfaces 255 256`PythonWin <https://web.archive.org/web/20060524042422/ 257https://www.python.org/windows/pythonwin/>`_ is a sample MFC application 258shipped with PyWin32. It is an embeddable IDE with a built-in debugger. 259 260.. seealso:: 261 262 `Win32 How Do I...? <http://timgolden.me.uk/python/win32_how_do_i.html>`_ 263 by Tim Golden 264 265 `Python and COM <http://www.boddie.org.uk/python/COM.html>`_ 266 by David and Paul Boddie 267 268 269Py2exe 270------ 271 272`Py2exe <http://www.py2exe.org/>`_ is a :mod:`distutils` extension (see 273:ref:`extending-distutils`) which wraps Python scripts into executable Windows 274programs (:file:`{*}.exe` files). When you have done this, you can distribute 275your application without requiring your users to install Python. 276 277 278WConio 279------ 280 281Since Python's advanced terminal handling layer, :mod:`curses`, is restricted to 282Unix-like systems, there is a library exclusive to Windows as well: Windows 283Console I/O for Python. 284 285`WConio <http://newcenturycomputers.net/projects/wconio.html>`_ is a wrapper for 286Turbo-C's :file:`CONIO.H`, used to create text user interfaces. 287 288 289 290Compiling Python on Windows 291=========================== 292 293If you want to compile CPython yourself, first thing you should do is get the 294`source <https://www.python.org/downloads/source/>`_. You can download either the 295latest release's source or just grab a fresh `checkout 296<https://docs.python.org/devguide/setup.html#getting-the-source-code>`_. 297 298For Microsoft Visual C++, which is the compiler with which official Python 299releases are built, the source tree contains solutions/project files. View the 300:file:`readme.txt` in their respective directories: 301 302+--------------------+--------------+-----------------------+ 303| Directory | MSVC version | Visual Studio version | 304+====================+==============+=======================+ 305| :file:`PC/VC6/` | 6.0 | 97 | 306+--------------------+--------------+-----------------------+ 307| :file:`PC/VS7.1/` | 7.1 | 2003 | 308+--------------------+--------------+-----------------------+ 309| :file:`PC/VS8.0/` | 8.0 | 2005 | 310+--------------------+--------------+-----------------------+ 311| :file:`PCbuild/` | 9.0 | 2008 | 312+--------------------+--------------+-----------------------+ 313 314Note that not all of these build directories are fully supported. Read the 315release notes to see which compiler version the official releases for your 316version are built with. 317 318Check :file:`PC/readme.txt` for general information on the build process. 319 320 321For extension modules, consult :ref:`building-on-windows`. 322 323.. seealso:: 324 325 `Python + Windows + distutils + SWIG + gcc MinGW <http://sebsauvage.net/python/mingw.html>`_ 326 or "Creating Python extensions in C/C++ with SWIG and compiling them with 327 MinGW gcc under Windows" or "Installing Python extension with distutils 328 and without Microsoft Visual C++" by Sébastien Sauvage, 2003 329 330 `MingW -- Python extensions <http://oldwiki.mingw.org/index.php/Python%20extensions>`_ 331 by Trent Apted et al, 2007 332 333 334Other resources 335=============== 336 337.. seealso:: 338 339 `Python Programming On Win32 <http://shop.oreilly.com/product/9781565926219.do>`_ 340 "Help for Windows Programmers" 341 by Mark Hammond and Andy Robinson, O'Reilly Media, 2000, 342 ISBN 1-56592-621-8 343 344 `A Python for Windows Tutorial <http://www.imladris.com/Scripts/PythonForWindows.html>`_ 345 by Amanda Birmingham, 2004 346 347