blob: 2b52544e045e420f6e57dade31e7e7a382ae0072 [file] [log] [blame]
Georg Brandl87983f22007-12-01 23:12:45 +00001.. 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<http://www.python.org/download/releases/>`_ for many years.
22
23With ongoing development of Python, some platforms that used to be supported
24earlier are not 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 <http://cygwin.com/>`_ installer offers to install the `Python
35 interpreter <http://cygwin.com/packages/python>`_ as well; it is located under
36 "Interpreters." (cf. `Cygwin package source
37 <ftp://ftp.uni-erlangen.de/pub/pc/gnuwin32/cygwin/mirrors/cygnus/
38 release/python>`_, `Maintainer releases
39 <http://www.tishler.net/jason/software/python/>`_)
40
41See `Python for Windows (and DOS) <http://www.python.org/download/windows/>`_
42for detailed information about platforms with precompiled installers.
43
44.. seealso::
45
46 `Python on XP <http://www.richarddooling.com/index.php/2006/03/14/python-on-xp-7-minutes-to-hello-world/>`_
47 "7 Minutes to "Hello World!""
48 by Richard Dooling, 2006
49
50 `Installing on Windows <http://diveintopython.org/installing_python/windows.html>`_
51 in "`Dive into Python: Python from novice to pro
52 <http://diveintopython.org/index.html>`_"
53 by Mark Pilgrim, 2004,
54 ISBN 1-59059-356-1
55
56 `For Windows users <http://swaroopch.com/text/Byte_of_Python:Installing_Python#For_Windows_users>`_
57 in "Installing Python"
58 in "`A Byte of Python <http://www.byteofpython.info>`_"
59 by Swaroop C H, 2003
60
61
62Alternative bundles
63===================
64
65Besides the standard CPython distribution, there are modified packages including
66additional functionality. The following is a list of popular versions and their
67key features:
68
69`ActivePython <http://www.activestate.com/Products/activepython/>`_
70 Installer with multi-platform compatibility, documentation, PyWin32
71
72`Python Enthought Edition <http://code.enthought.com/enthon/>`_
73 Popular modules (such as PyWin32) with their respective documentation, tool
74 suite for building extensible python applications
75
Georg Brandl013d5742007-12-07 15:16:57 +000076Notice that these packages are likely to install *older* versions of Python.
77
Georg Brandl87983f22007-12-01 23:12:45 +000078
79
80Configuring Python
81==================
82
83In order to run Python flawlessly, you might have to change certain environment
84settings in Windows.
85
86
87Excursus: Setting environment variables
88---------------------------------------
89
Georg Brandl013d5742007-12-07 15:16:57 +000090Windows has a built-in dialog for changing environment variables (following
91guide applies to XP classical view): Right-click the icon for your machine
92(usually located on your Desktop and called "My Computer") and choose
93:menuselection:`Properties` there. Then, open the :guilabel:`Advanced` tab
94and click the :guilabel:`Environment Variables` button.
Georg Brandl87983f22007-12-01 23:12:45 +000095
96In short, your path is:
97
98 :menuselection:`My Computer
99 --> Properties
100 --> Advanced
101 --> Environment Variables`
102
103In this dialog, you can add or modify User and System variables. To change
104System variables, you need non-restricted access to your machine
105(i.e. Administrator rights).
106
107Another way of adding variables to your environment is using the :command:`set`
108command::
109
110 set PYTHONPATH=%PYTHONPATH%;C:\My_python_lib
111
112To make this setting permanent, you could add the corresponding command line to
Georg Brandl013d5742007-12-07 15:16:57 +0000113your :file:`autoexec.bat`. :program:`msconfig` is a graphical interface to this
114file.
Georg Brandl87983f22007-12-01 23:12:45 +0000115
116Viewing environment variables can also be done more straight-forward: The
117command prompt will expand strings wrapped into percent signs automatically::
118
119 echo %PATH%
120
121Consult :command:`set /?` for details on this behaviour.
122
123.. seealso::
124
125 http://support.microsoft.com/kb/100843
126 Environment variables in Windows NT
127
128 http://support.microsoft.com/kb/310519
129 How To Manage Environment Variables in Windows XP
130
Georg Brandl013d5742007-12-07 15:16:57 +0000131 http://www.chem.gla.ac.uk/~louis/software/faq/q1.html
132 Setting Environment variables, Louis J. Farrugia
133
Georg Brandl87983f22007-12-01 23:12:45 +0000134
135Finding the Python executable
136-----------------------------
137
138Besides using the automatically created start menu entry for the Python
139interpreter, you might want to start Python in the DOS prompt. To make this
140work, you need to set your :envvar:`%PATH%` environment variable to include the
141directory of your Python distribution, delimited by a semicolon from other
142entries. An example variable could look like this (assuming the first two
143entries are Windows' default)::
144
145 C:\WINNT\system32;C:\WINNT;C:\Python25
146
147Typing :command:`python` on your command prompt will now fire up the Python
148interpreter. Thus, you can also execute your scripts with command line options,
149see :ref:`using-on-cmdline` documentation.
150
151
152Finding modules
153---------------
154
155Python usually stores its library (and thereby your site-packages folder) in the
156installation directory. So, if you had installed Python to
157:file:`C:\\Python\\`, the default library would reside in
158:file:`C:\\Python\\Lib\\` and third-party modules should be stored in
159:file:`C:\\Python\\Lib\\site-packages\\`.
160
Georg Brandlb19be572007-12-29 10:57:00 +0000161.. `` this fixes syntax highlighting errors in some editors due to the \\ hackery
Georg Brandl87983f22007-12-01 23:12:45 +0000162
163You can add folders to your search path to make Python's import mechanism search
164in these directories as well. Use :envvar:`PYTHONPATH`, as described in
165:ref:`using-on-envvars`, to modify :data:`sys.path`. On Windows, paths are
166separated by semicolons, though, to distinguish them from drive identifiers
167(:file:`C:\\` etc.).
168
Georg Brandlb19be572007-12-29 10:57:00 +0000169.. ``
Georg Brandl87983f22007-12-01 23:12:45 +0000170
171Modifying the module search path can also be done through the Windows registry:
172Edit
173:file:`HKEY_LOCAL_MACHINE\\SOFTWARE\\Python\\PythonCore\\{version}\\PythonPath\\`,
174as described above for the environment variable :envvar:`%PYTHONPATH%`. A
175convenient registry editor is :program:`regedit` (start it by typing "regedit"
176into :menuselection:`Start --> Run`).
177
178
179Executing scripts
180-----------------
181
182Python scripts (files with the extension ``.py``) will be executed by
183:program:`python.exe` by default. This executable opens a terminal, which stays
184open even if the program uses a GUI. If you do not want this to happen, use the
185extension ``.pyw`` which will cause the script to be executed by
186:program:`pythonw.exe` by default (both executables are located in the top-level
187of your Python installation directory). This suppresses the terminal window on
188startup.
189
190You can also make all ``.py`` scripts execute with :program:`pythonw.exe`,
191setting this through the usual facilites, for example (names might differ,
192depending on your version of Windows):
193
194#. Open the context menu of a :file:`{*}.py` file.
195#. Click :menuselection:`Open with...`.
196#. Choose the interpreter of your choice (utilize :guilabel:`Other...` or
197 :guilabel:`Choose Program...` if it is not in the list of default programs).
198#. Check :guilabel:`Always open files with this program`.
199#. Click :guilabel:`OK`.
200
201
202
203Additional modules
204==================
205
206Even though Python aims to be portable among all platforms, there are features
207that are unique to Windows. A couple of modules, both in the standard library
208and external, and snippets exist to use these features.
209
210The Windows-specific standard modules are documented in
211:ref:`mswin-specific-services`.
212
213
214PyWin32
215-------
216
217The `PyWin32 <http://python.net/crew/mhammond/win32/>`_ module by Mark Hammond
218is a collection of modules for advanced Windows-specific support. This includes
219utilites for:
220
221* `Component Object Model <http://www.microsoft.com/com/>`_ (COM)
222* Win32 API calls
223* Registry
224* Event log
225* `Microsoft Foundation Classes <http://msdn.microsoft.com/library/
226 en-us/vclib/html/_mfc_Class_Library_Reference_Introduction.asp>`_ (MFC)
227 user interfaces
228
229`PythonWin <http://web.archive.org/web/20060524042422/
230http://www.python.org/windows/pythonwin/>`_ is a sample MFC application
231shipped with PyWin32. It is an embeddable IDE with a built-in debugger.
232
233.. seealso::
234
235 `Win32 How Do I...? <http://timgolden.me.uk/python/win32_how_do_i.html>`_
236 by Tim Golden
237
238 `Python and COM <http://www.boddie.org.uk/python/COM.html>`_
239 by David and Paul Boddie
240
241
242Py2exe
243------
244
245`Py2exe <http://www.py2exe.org/>`_ is a :mod:`distutils` extension (see
246:ref:`extending-distutils`) which wraps Python scripts into executable Windows
247programs (:file:`{*}.exe` files). When you have done this, you can distribute
248your application without requiring your users to install Python.
249
250
251WConio
252------
253
254Since Python's advanced terminal handling layer, :mod:`curses`, is restricted to
255Unix-like systems, there is a library exclusive to Windows as well: Windows
256Console I/O for Python.
257
258`WConio <http://newcenturycomputers.net/projects/wconio.html>`_ is a wrapper for
259Turbo-C's :file:`CONIO.H`, used to create text user interfaces.
260
261
262
263Compiling Python on Windows
264===========================
265
266If you want to compile CPython yourself, first thing you should do is get the
267`source <http://python.org/download/source/>`_. You can download either the
268latest release's source or just grab a fresh `checkout
Georg Brandld95a1ee2007-12-04 16:10:02 +0000269<http://www.python.org/dev/faq/#how-do-i-get-a-checkout-of-the-repository-read-only-and-read-write>`_.
Georg Brandl87983f22007-12-01 23:12:45 +0000270
271For Microsoft Visual C++, which is the compiler with which official Python
272releases are built, the source tree contains solutions/project files. View the
273:file:`readme.txt` in their respective directories:
274
275+--------------------+--------------+-----------------------+
276| Directory | MSVC version | Visual Studio version |
277+====================+==============+=======================+
Georg Brandl001e8382007-12-16 23:11:16 +0000278| :file:`PC/VC6/` | 6.0 | 97 |
Georg Brandl87983f22007-12-01 23:12:45 +0000279+--------------------+--------------+-----------------------+
280| :file:`PCbuild/` | 7.1 | 2003 |
281+--------------------+--------------+-----------------------+
282| :file:`PCbuild8/` | 8.0 | 2005 |
283+--------------------+--------------+-----------------------+
284| :file:`PCbuild9/` | 9.0 | 2008 |
285+--------------------+--------------+-----------------------+
286
287Note that not all of these build directories are fully supported. Read the
288release notes to see which compiler version the official releases for your
289version are built with.
290
291Check :file:`PC/readme.txt` for general information on the build process.
292
293
294For extension modules, consult :ref:`building-on-windows`.
295
296.. seealso::
297
298 `Python + Windows + distutils + SWIG + gcc MinGW <http://sebsauvage.net/python/mingw.html>`_
299 or "Creating Python extensions in C/C++ with SWIG and compiling them with
300 MinGW gcc under Windows" or "Installing Python extension with distutils
301 and without Microsoft Visual C++" by Sébastien Sauvage, 2003
302
303 `MingW -- Python extensions <http://www.mingw.org/MinGWiki/index.php/Python%20extensions>`_
304 by Trent Apted et al, 2007
305
306
307Other resources
308===============
309
310.. seealso::
311
312 `Python Programming On Win32 <http://www.oreilly.com/catalog/pythonwin32/>`_
313 "Help for Windows Programmers"
314 by Mark Hammond and Andy Robinson, O'Reilly Media, 2000,
315 ISBN 1-56592-621-8
316
317 `A Python for Windows Tutorial <http://www.imladris.com/Scripts/PythonForWindows.html>`_
318 by Amanda Birmingham, 2004
319