/Doc/using/windows.rst

  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<http://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 <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
 76Notice that these packages are likely to install *older* versions of Python.
 77
 78
 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
 90Windows 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.
 95
 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
113your :file:`autoexec.bat`. :program:`msconfig` is a graphical interface to this
114file.
115
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
131   http://www.chem.gla.ac.uk/~louis/software/faq/q1.html
132      Setting Environment variables, Louis J. Farrugia
133
134
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:\WINDOWS\system32;C:\WINDOWS;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
161.. `` this fixes syntax highlighting errors in some editors due to the \\ hackery
162
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
169.. ``
170
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 facilities, for example (might require
192administrative rights):
193
194#. Launch a command prompt.
195#. Associate the correct file group with ``.py`` scripts::
196
197      assoc .py=Python.File
198
199#. Redirect all Python files to the new executable::
200
201      ftype Python.File=C:\Path\to\pythonw.exe "%1" %*
202
203
204Additional modules
205==================
206
207Even though Python aims to be portable among all platforms, there are features
208that are unique to Windows.  A couple of modules, both in the standard library
209and external, and snippets exist to use these features.
210
211The Windows-specific standard modules are documented in
212:ref:`mswin-specific-services`.
213
214
215PyWin32
216-------
217
218The `PyWin32 <http://python.net/crew/mhammond/win32/>`_ module by Mark Hammond
219is a collection of modules for advanced Windows-specific support.  This includes
220utilities for:
221
222* `Component Object Model <http://www.microsoft.com/com/>`_ (COM)
223* Win32 API calls
224* Registry
225* Event log
226* `Microsoft Foundation Classes <http://msdn.microsoft.com/library/
227  en-us/vclib/html/_mfc_Class_Library_Reference_Introduction.asp>`_ (MFC)
228  user interfaces
229
230`PythonWin <http://web.archive.org/web/20060524042422/
231http://www.python.org/windows/pythonwin/>`_ is a sample MFC application
232shipped with PyWin32.  It is an embeddable IDE with a built-in debugger.
233
234.. seealso::
235
236   `Win32 How Do I...? <http://timgolden.me.uk/python/win32_how_do_i.html>`_
237      by Tim Golden
238
239   `Python and COM <http://www.boddie.org.uk/python/COM.html>`_
240      by David and Paul Boddie
241
242
243Py2exe
244------
245
246`Py2exe <http://www.py2exe.org/>`_ is a :mod:`distutils` extension (see
247:ref:`extending-distutils`) which wraps Python scripts into executable Windows
248programs (:file:`{*}.exe` files).  When you have done this, you can distribute
249your application without requiring your users to install Python.
250
251
252WConio
253------
254
255Since Python's advanced terminal handling layer, :mod:`curses`, is restricted to
256Unix-like systems, there is a library exclusive to Windows as well: Windows
257Console I/O for Python.
258
259`WConio <http://newcenturycomputers.net/projects/wconio.html>`_ is a wrapper for
260Turbo-C's :file:`CONIO.H`, used to create text user interfaces.
261
262
263
264Compiling Python on Windows
265===========================
266
267If you want to compile CPython yourself, first thing you should do is get the
268`source <http://python.org/download/source/>`_. You can download either the
269latest release's source or just grab a fresh `checkout
270<http://www.python.org/dev/faq/#how-do-i-get-a-checkout-of-the-repository-read-only-and-read-write>`_.
271
272For Microsoft Visual C++, which is the compiler with which official Python
273releases are built, the source tree contains solutions/project files.  View the
274:file:`readme.txt` in their respective directories:
275
276+--------------------+--------------+-----------------------+
277| Directory          | MSVC version | Visual Studio version |
278+====================+==============+=======================+
279| :file:`PC/VC6/`    | 6.0          | 97                    |
280+--------------------+--------------+-----------------------+
281| :file:`PC/VS7.1/`  | 7.1          | 2003                  |
282+--------------------+--------------+-----------------------+
283| :file:`PC/VS8.0/`  | 8.0          | 2005                  |
284+--------------------+--------------+-----------------------+
285| :file:`PCbuild/`   | 9.0          | 2008                  |
286+--------------------+--------------+-----------------------+
287
288Note that not all of these build directories are fully supported.  Read the
289release notes to see which compiler version the official releases for your
290version are built with.
291
292Check :file:`PC/readme.txt` for general information on the build process.
293
294
295For extension modules, consult :ref:`building-on-windows`.
296
297.. seealso::
298
299   `Python + Windows + distutils + SWIG + gcc MinGW <http://sebsauvage.net/python/mingw.html>`_
300      or "Creating Python extensions in C/C++ with SWIG and compiling them with
301      MinGW gcc under Windows" or "Installing Python extension with distutils
302      and without Microsoft Visual C++" by SĂŠbastien Sauvage, 2003
303
304   `MingW -- Python extensions <http://www.mingw.org/MinGWiki/index.php/Python%20extensions>`_
305      by Trent Apted et al, 2007
306
307
308Other resources
309===============
310
311.. seealso::
312
313   `Python Programming On Win32 <http://www.oreilly.com/catalog/pythonwin32/>`_
314      "Help for Windows Programmers"
315      by Mark Hammond and Andy Robinson, O'Reilly Media, 2000,
316      ISBN 1-56592-621-8
317
318   `A Python for Windows Tutorial <http://www.imladris.com/Scripts/PythonForWindows.html>`_
319      by Amanda Birmingham, 2004
320