1
.. highlightlang:: none
5
*************************
6
Using Python on Windows
7
*************************
9
.. sectionauthor:: Robert Lehmann <lehmannro@gmail.com>
11
This document aims to give an overview of Windows-specific behaviour you should
12
know about when using Python on Microsoft Windows.
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.
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.
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 <http://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/>`_)
40
See `Python for Windows (and DOS) <https://www.python.org/download/windows/>`_
41
for detailed information about platforms with precompiled installers.
45
`Python on XP <http://www.richarddooling.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
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,
55
`For Windows users <http://www.swaroopch.com/notes/python/#install_windows>`_
56
in "Installing Python"
57
in "`A Byte of Python <http://www.swaroopch.com/notes/python/>`_"
64
Besides the standard CPython distribution, there are modified packages including
65
additional functionality. The following is a list of popular versions and their
68
`ActivePython <http://www.activestate.com/Products/activepython/>`_
69
Installer with multi-platform compatibility, documentation, PyWin32
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
75
Notice that these packages are likely to install *older* versions of Python.
82
In order to run Python flawlessly, you might have to change certain environment
88
Excursus: Setting environment variables
89
---------------------------------------
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.
97
In short, your path is:
99
:menuselection:`My Computer
102
--> Environment Variables`
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).
108
Another way of adding variables to your environment is using the :command:`set`
111
set PYTHONPATH=%PYTHONPATH%;C:\My_python_lib
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
117
Viewing environment variables can also be done more straight-forward: The
118
command prompt will expand strings wrapped into percent signs automatically::
122
Consult :command:`set /?` for details on this behaviour.
126
http://support.microsoft.com/kb/100843
127
Environment variables in Windows NT
129
http://support.microsoft.com/kb/310519
130
How To Manage Environment Variables in Windows XP
132
http://www.chem.gla.ac.uk/~louis/software/faq/q1.html
133
Setting Environment variables, Louis J. Farrugia
136
Finding the Python executable
137
-----------------------------
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)::
146
C:\WINDOWS\system32;C:\WINDOWS;C:\Python25
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.
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\\`.
162
This is how :data:`sys.path` is populated on Windows:
164
* An empty entry is added at the start, which corresponds to the current
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.).
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.)
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.
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).
190
The end result of all this is:
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.
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.
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
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
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):
221
#. Launch a command prompt.
222
#. Associate the correct file group with ``.py`` scripts::
224
assoc .py=Python.File
226
#. Redirect all Python files to the new executable::
228
ftype Python.File=C:\Path\to\pythonw.exe "%1" %*
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.
238
The Windows-specific standard modules are documented in
239
:ref:`mswin-specific-services`.
245
The `PyWin32 <http://python.net/crew/mhammond/win32/>`_ module by Mark Hammond
246
is a collection of modules for advanced Windows-specific support. This includes
249
* `Component Object Model <http://www.microsoft.com/com/>`_ (COM)
253
* `Microsoft Foundation Classes <http://msdn.microsoft.com/en-us/library/fe1cf721%28VS.80%29.aspx>`_ (MFC)
256
`PythonWin <http://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.
262
`Win32 How Do I...? <http://timgolden.me.uk/python/win32_how_do_i.html>`_
265
`Python and COM <http://www.boddie.org.uk/python/COM.html>`_
266
by David and Paul Boddie
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.
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.
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.
290
Compiling Python on Windows
291
===========================
293
If you want to compile CPython yourself, first thing you should do is get the
294
`source <https://www.python.org/download/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>`_.
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:
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
+--------------------+--------------+-----------------------+
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.
318
Check :file:`PC/readme.txt` for general information on the build process.
321
For extension modules, consult :ref:`building-on-windows`.
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
330
`MingW -- Python extensions <http://oldwiki.mingw.org/index.php/Python%20extensions>`_
331
by Trent Apted et al, 2007
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,
344
`A Python for Windows Tutorial <http://www.imladris.com/Scripts/PythonForWindows.html>`_
345
by Amanda Birmingham, 2004