|
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 |
|
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 <http://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 <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 |
|
41 See `Python for Windows (and DOS) <http://www.python.org/download/windows/>`_ |
|
42 for 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 |
|
62 Alternative bundles |
|
63 =================== |
|
64 |
|
65 Besides the standard CPython distribution, there are modified packages including |
|
66 additional functionality. The following is a list of popular versions and their |
|
67 key 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 |
|
76 Notice that these packages are likely to install *older* versions of Python. |
|
77 |
|
78 |
|
79 |
|
80 Configuring Python |
|
81 ================== |
|
82 |
|
83 In order to run Python flawlessly, you might have to change certain environment |
|
84 settings in Windows. |
|
85 |
|
86 |
|
87 Excursus: Setting environment variables |
|
88 --------------------------------------- |
|
89 |
|
90 Windows has a built-in dialog for changing environment variables (following |
|
91 guide 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 |
|
94 and click the :guilabel:`Environment Variables` button. |
|
95 |
|
96 In short, your path is: |
|
97 |
|
98 :menuselection:`My Computer |
|
99 --> Properties |
|
100 --> Advanced |
|
101 --> Environment Variables` |
|
102 |
|
103 In this dialog, you can add or modify User and System variables. To change |
|
104 System variables, you need non-restricted access to your machine |
|
105 (i.e. Administrator rights). |
|
106 |
|
107 Another way of adding variables to your environment is using the :command:`set` |
|
108 command:: |
|
109 |
|
110 set PYTHONPATH=%PYTHONPATH%;C:\My_python_lib |
|
111 |
|
112 To make this setting permanent, you could add the corresponding command line to |
|
113 your :file:`autoexec.bat`. :program:`msconfig` is a graphical interface to this |
|
114 file. |
|
115 |
|
116 Viewing environment variables can also be done more straight-forward: The |
|
117 command prompt will expand strings wrapped into percent signs automatically:: |
|
118 |
|
119 echo %PATH% |
|
120 |
|
121 Consult :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 |
|
135 Finding the Python executable |
|
136 ----------------------------- |
|
137 |
|
138 Besides using the automatically created start menu entry for the Python |
|
139 interpreter, you might want to start Python in the DOS prompt. To make this |
|
140 work, you need to set your :envvar:`%PATH%` environment variable to include the |
|
141 directory of your Python distribution, delimited by a semicolon from other |
|
142 entries. An example variable could look like this (assuming the first two |
|
143 entries are Windows' default):: |
|
144 |
|
145 C:\WINDOWS\system32;C:\WINDOWS;C:\Python25 |
|
146 |
|
147 Typing :command:`python` on your command prompt will now fire up the Python |
|
148 interpreter. Thus, you can also execute your scripts with command line options, |
|
149 see :ref:`using-on-cmdline` documentation. |
|
150 |
|
151 |
|
152 Finding modules |
|
153 --------------- |
|
154 |
|
155 Python usually stores its library (and thereby your site-packages folder) in the |
|
156 installation 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 |
|
163 You can add folders to your search path to make Python's import mechanism search |
|
164 in these directories as well. Use :envvar:`PYTHONPATH`, as described in |
|
165 :ref:`using-on-envvars`, to modify :data:`sys.path`. On Windows, paths are |
|
166 separated by semicolons, though, to distinguish them from drive identifiers |
|
167 (:file:`C:\\` etc.). |
|
168 |
|
169 .. `` |
|
170 |
|
171 Modifying the module search path can also be done through the Windows registry: |
|
172 Edit |
|
173 :file:`HKEY_LOCAL_MACHINE\\SOFTWARE\\Python\\PythonCore\\{version}\\PythonPath\\`, |
|
174 as described above for the environment variable :envvar:`%PYTHONPATH%`. A |
|
175 convenient registry editor is :program:`regedit` (start it by typing "regedit" |
|
176 into :menuselection:`Start --> Run`). |
|
177 |
|
178 |
|
179 Executing scripts |
|
180 ----------------- |
|
181 |
|
182 Python scripts (files with the extension ``.py``) will be executed by |
|
183 :program:`python.exe` by default. This executable opens a terminal, which stays |
|
184 open even if the program uses a GUI. If you do not want this to happen, use the |
|
185 extension ``.pyw`` which will cause the script to be executed by |
|
186 :program:`pythonw.exe` by default (both executables are located in the top-level |
|
187 of your Python installation directory). This suppresses the terminal window on |
|
188 startup. |
|
189 |
|
190 You can also make all ``.py`` scripts execute with :program:`pythonw.exe`, |
|
191 setting this through the usual facilities, for example (might require |
|
192 administrative 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 |
|
204 Additional modules |
|
205 ================== |
|
206 |
|
207 Even though Python aims to be portable among all platforms, there are features |
|
208 that are unique to Windows. A couple of modules, both in the standard library |
|
209 and external, and snippets exist to use these features. |
|
210 |
|
211 The Windows-specific standard modules are documented in |
|
212 :ref:`mswin-specific-services`. |
|
213 |
|
214 |
|
215 PyWin32 |
|
216 ------- |
|
217 |
|
218 The `PyWin32 <http://python.net/crew/mhammond/win32/>`_ module by Mark Hammond |
|
219 is a collection of modules for advanced Windows-specific support. This includes |
|
220 utilities 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/ |
|
231 http://www.python.org/windows/pythonwin/>`_ is a sample MFC application |
|
232 shipped 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 |
|
243 Py2exe |
|
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 |
|
248 programs (:file:`{*}.exe` files). When you have done this, you can distribute |
|
249 your application without requiring your users to install Python. |
|
250 |
|
251 |
|
252 WConio |
|
253 ------ |
|
254 |
|
255 Since Python's advanced terminal handling layer, :mod:`curses`, is restricted to |
|
256 Unix-like systems, there is a library exclusive to Windows as well: Windows |
|
257 Console I/O for Python. |
|
258 |
|
259 `WConio <http://newcenturycomputers.net/projects/wconio.html>`_ is a wrapper for |
|
260 Turbo-C's :file:`CONIO.H`, used to create text user interfaces. |
|
261 |
|
262 |
|
263 |
|
264 Compiling Python on Windows |
|
265 =========================== |
|
266 |
|
267 If 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 |
|
269 latest 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 |
|
272 For Microsoft Visual C++, which is the compiler with which official Python |
|
273 releases 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 |
|
288 Note that not all of these build directories are fully supported. Read the |
|
289 release notes to see which compiler version the official releases for your |
|
290 version are built with. |
|
291 |
|
292 Check :file:`PC/readme.txt` for general information on the build process. |
|
293 |
|
294 |
|
295 For 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 |
|
308 Other 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 |