1 .. highlightlang:: none 2 3 .. _using-on-windows: 4 5 ************************* 6 Using Python on Windows 7 ************************* 8 9 .. sectionauthor:: Robert Lehmann <lehmannro (a] gmail.com> 10 11 This document aims to give an overview of Windows-specific behaviour you should 12 know about when using Python on Microsoft Windows. 13 14 15 Installing Python 16 ================= 17 18 Unlike most Unix systems and services, Windows does not require Python natively 19 and thus does not pre-install a version of Python. However, the CPython team 20 has compiled Windows installers (MSI packages) with every `release 21 <https://www.python.org/download/releases/>`_ for many years. 22 23 With ongoing development of Python, some platforms that used to be supported 24 earlier are no longer supported (due to the lack of users or developers). 25 Check :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 40 See `Python for Windows (and DOS) <https://www.python.org/download/windows/>`_ 41 for 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 61 Alternative bundles 62 =================== 63 64 Besides the standard CPython distribution, there are modified packages including 65 additional functionality. The following is a list of popular versions and their 66 key 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 75 Notice that these packages are likely to install *older* versions of Python. 76 77 78 79 Configuring Python 80 ================== 81 82 In order to run Python flawlessly, you might have to change certain environment 83 settings in Windows. 84 85 86 .. _setting-envvars: 87 88 Excursus: Setting environment variables 89 --------------------------------------- 90 91 Windows has a built-in dialog for changing environment variables (following 92 guide 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 95 and click the :guilabel:`Environment Variables` button. 96 97 In short, your path is: 98 99 :menuselection:`My Computer 100 --> Properties 101 --> Advanced 102 --> Environment Variables` 103 104 In this dialog, you can add or modify User and System variables. To change 105 System variables, you need non-restricted access to your machine 106 (i.e. Administrator rights). 107 108 Another way of adding variables to your environment is using the :command:`set` 109 command:: 110 111 set PYTHONPATH=%PYTHONPATH%;C:\My_python_lib 112 113 To make this setting permanent, you could add the corresponding command line to 114 your :file:`autoexec.bat`. :program:`msconfig` is a graphical interface to this 115 file. 116 117 Viewing environment variables can also be done more straight-forward: The 118 command prompt will expand strings wrapped into percent signs automatically:: 119 120 echo %PATH% 121 122 Consult :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 136 Finding the Python executable 137 ----------------------------- 138 139 Besides using the automatically created start menu entry for the Python 140 interpreter, you might want to start Python in the DOS prompt. To make this 141 work, you need to set your :envvar:`%PATH%` environment variable to include the 142 directory of your Python distribution, delimited by a semicolon from other 143 entries. An example variable could look like this (assuming the first two 144 entries are Windows' default):: 145 146 C:\WINDOWS\system32;C:\WINDOWS;C:\Python25 147 148 Typing :command:`python` on your command prompt will now fire up the Python 149 interpreter. Thus, you can also execute your scripts with command line options, 150 see :ref:`using-on-cmdline` documentation. 151 152 153 Finding modules 154 --------------- 155 156 Python usually stores its library (and thereby your site-packages folder) in the 157 installation 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 162 This 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 190 The 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 206 Executing scripts 207 ----------------- 208 209 Python scripts (files with the extension ``.py``) will be executed by 210 :program:`python.exe` by default. This executable opens a terminal, which stays 211 open even if the program uses a GUI. If you do not want this to happen, use the 212 extension ``.pyw`` which will cause the script to be executed by 213 :program:`pythonw.exe` by default (both executables are located in the top-level 214 of your Python installation directory). This suppresses the terminal window on 215 startup. 216 217 You can also make all ``.py`` scripts execute with :program:`pythonw.exe`, 218 setting this through the usual facilities, for example (might require 219 administrative 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 231 Additional modules 232 ================== 233 234 Even though Python aims to be portable among all platforms, there are features 235 that are unique to Windows. A couple of modules, both in the standard library 236 and external, and snippets exist to use these features. 237 238 The Windows-specific standard modules are documented in 239 :ref:`mswin-specific-services`. 240 241 242 PyWin32 243 ------- 244 245 The `PyWin32 <https://pypi.python.org/pypi/pywin32>`_ module by Mark Hammond 246 is a collection of modules for advanced Windows-specific support. This includes 247 utilities 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/ 257 https://www.python.org/windows/pythonwin/>`_ is a sample MFC application 258 shipped 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 269 Py2exe 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 274 programs (:file:`{*}.exe` files). When you have done this, you can distribute 275 your application without requiring your users to install Python. 276 277 278 WConio 279 ------ 280 281 Since Python's advanced terminal handling layer, :mod:`curses`, is restricted to 282 Unix-like systems, there is a library exclusive to Windows as well: Windows 283 Console I/O for Python. 284 285 `WConio <http://newcenturycomputers.net/projects/wconio.html>`_ is a wrapper for 286 Turbo-C's :file:`CONIO.H`, used to create text user interfaces. 287 288 289 290 Compiling Python on Windows 291 =========================== 292 293 If 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 295 latest release's source or just grab a fresh `checkout 296 <https://docs.python.org/devguide/setup.html#getting-the-source-code>`_. 297 298 For Microsoft Visual C++, which is the compiler with which official Python 299 releases 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 314 Note that not all of these build directories are fully supported. Read the 315 release notes to see which compiler version the official releases for your 316 version are built with. 317 318 Check :file:`PC/readme.txt` for general information on the build process. 319 320 321 For 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 Sbastien Sauvage, 2003 329 330 `MingW -- Python extensions <http://oldwiki.mingw.org/index.php/Python%20extensions>`_ 331 by Trent Apted et al, 2007 332 333 334 Other 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
