1
.. highlightlang:: none
5
*************************
6
Using Python on Windows
7
*************************
9
.. sectionauthor:: Robert Lehmann <lehmannro@gmail.com>
10
.. sectionauthor:: Steve Dower <steve.dower@microsoft.com>
12
This document aims to give an overview of Windows-specific behaviour you should
13
know about when using Python on Microsoft Windows.
18
Unlike most Unix systems and services, Windows does not include a system
19
supported installation of Python. To make Python available, the CPython team
20
has compiled Windows installers (MSI packages) with every `release
21
<https://www.python.org/download/releases/>`_ for many years. These installers
22
are primarily intended to add a per-user installation of Python, with the
23
core interpreter and library being used by a single user. The installer is also
24
able to install for all users of a single machine, and a separate ZIP file is
25
available for application-local distributions.
30
As specified in :pep:`11`, a Python release only supports a Windows platform
31
while Microsoft considers the platform under extended support. This means that
32
Python 3.5 supports Windows Vista and newer. If you require Windows XP support
33
then please install Python 3.4.
38
Four Python 3.5 installers are available for download - two each for the 32-bit
39
and 64-bit versions of the interpreter. The *web installer* is a small initial
40
download, and it will automatically download the required components as
41
necessary. The *offline installer* includes the components necessary for a
42
default installation and only requires an internet connection for optional
43
features. See :ref:`install-layout-option` for other ways to avoid downloading
46
After starting the installer, one of two options may be selected:
48
.. image:: win_installer.png
50
If you select "Install Now":
52
* You will *not* need to be an administrator (unless a system update for the
53
C Runtime Library is required or you install the :ref:`launcher` for all
55
* Python will be installed into your user directory
56
* The :ref:`launcher` will be installed according to the option at the bottom
58
* The standard library, test suite, launcher and pip will be installed
59
* If selected, the install directory will be added to your :envvar:`PATH`
60
* Shortcuts will only be visible for the current user
62
Selecting "Customize installation" will allow you to select the features to
63
install, the installation location and other options or post-install actions.
64
To install debugging symbols or binaries, you will need to use this option.
66
To perform an all-users installation, you should select "Customize
67
installation". In this case:
69
* You may be required to provide administrative credentials or approval
70
* Python will be installed into the Program Files directory
71
* The :ref:`launcher` will be installed into the Windows directory
72
* Optional features may be selected during installation
73
* The standard library can be pre-compiled to bytecode
74
* If selected, the install directory will be added to the system :envvar:`PATH`
75
* Shortcuts are available for all users
77
.. _install-quiet-option:
82
All of the options available in the installer UI can also be specified from the
83
command line, allowing scripted installers to replicate an installation on many
84
machines without user interaction. These options may also be set without
85
suppressing the UI in order to change some of the defaults.
87
To completely hide the installer UI and install Python silently, pass the
88
``/quiet`` option. To skip past the user interaction but still display
89
progress and errors, pass the ``/passive`` option. The ``/uninstall``
90
option may be passed to immediately begin removing Python - no prompt will be
93
All other options are passed as ``name=value``, where the value is usually
94
``0`` to disable a feature, ``1`` to enable a feature, or a path. The full list
95
of available options is shown below.
97
+---------------------------+--------------------------------------+--------------------------+
98
| Name | Description | Default |
99
+===========================+======================================+==========================+
100
| InstallAllUsers | Perform a system-wide installation. | 0 |
101
+---------------------------+--------------------------------------+--------------------------+
102
| TargetDir | The installation directory | Selected based on |
103
| | | InstallAllUsers |
104
+---------------------------+--------------------------------------+--------------------------+
105
| DefaultAllUsersTargetDir | The default installation directory | :file:`%ProgramFiles%\\\ |
106
| | for all-user installs | Python X.Y` or :file:`\ |
107
| | | %ProgramFiles(x86)%\\\ |
109
+---------------------------+--------------------------------------+--------------------------+
110
| DefaultJustForMeTargetDir | The default install directory for | :file:`%LocalAppData%\\\ |
111
| | just-for-me installs | Programs\\PythonXY` or |
112
| | | :file:`%LocalAppData%\\\ |
113
| | | Programs\\PythonXY-32` |
114
+---------------------------+--------------------------------------+--------------------------+
115
| DefaultCustomTargetDir | The default custom install directory | (empty) |
116
| | displayed in the UI | |
117
+---------------------------+--------------------------------------+--------------------------+
118
| AssociateFiles | Create file associations if the | 1 |
119
| | launcher is also installed. | |
120
+---------------------------+--------------------------------------+--------------------------+
121
| CompileAll | Compile all ``.py`` files to | 0 |
123
+---------------------------+--------------------------------------+--------------------------+
124
| PrependPath | Add install and Scripts directories | 0 |
125
| | tho :envvar:`PATH` and ``.PY`` to | |
126
| | :envvar:`PATHEXT` | |
127
+---------------------------+--------------------------------------+--------------------------+
128
| Shortcuts | Create shortcuts for the interpreter,| 1 |
129
| | documentation and IDLE if installed. | |
130
+---------------------------+--------------------------------------+--------------------------+
131
| Include_doc | Install Python manual | 1 |
132
+---------------------------+--------------------------------------+--------------------------+
133
| Include_debug | Install debug binaries | 0 |
134
+---------------------------+--------------------------------------+--------------------------+
135
| Include_dev | Install developer headers and | 1 |
137
+---------------------------+--------------------------------------+--------------------------+
138
| Include_exe | Install :file:`python.exe` and | 1 |
139
| | related files | |
140
+---------------------------+--------------------------------------+--------------------------+
141
| Include_launcher | Install :ref:`launcher`. | 1 |
142
+---------------------------+--------------------------------------+--------------------------+
143
| InstallLauncherAllUsers | Installs :ref:`launcher` for all | 1 |
145
+---------------------------+--------------------------------------+--------------------------+
146
| Include_lib | Install standard library and | 1 |
147
| | extension modules | |
148
+---------------------------+--------------------------------------+--------------------------+
149
| Include_pip | Install bundled pip and setuptools | 1 |
150
+---------------------------+--------------------------------------+--------------------------+
151
| Include_symbols | Install debugging symbols (`*`.pdb) | 0 |
152
+---------------------------+--------------------------------------+--------------------------+
153
| Include_tcltk | Install Tcl/Tk support and IDLE | 1 |
154
+---------------------------+--------------------------------------+--------------------------+
155
| Include_test | Install standard library test suite | 1 |
156
+---------------------------+--------------------------------------+--------------------------+
157
| Include_tools | Install utility scripts | 1 |
158
+---------------------------+--------------------------------------+--------------------------+
159
| LauncherOnly | Only installs the launcher. This | 0 |
160
| | will override most other options. | |
161
+---------------------------+--------------------------------------+--------------------------+
162
| SimpleInstall | Disable most install UI | 0 |
163
+---------------------------+--------------------------------------+--------------------------+
164
| SimpleInstallDescription | A custom message to display when the | (empty) |
165
| | simplified install UI is used. | |
166
+---------------------------+--------------------------------------+--------------------------+
168
For example, to silently install a default, system-wide Python installation,
169
you could use the following command (from an elevated command prompt)::
171
python-3.5.0.exe /quiet InstallAllUsers=1 PrependPath=1 Include_test=0
173
To allow users to easily install a personal copy of Python without the test
174
suite, you could provide a shortcut with the following command. This will
175
display a simplified initial page and disallow customization::
177
python-3.5.0.exe InstallAllUsers=0 Include_launcher=0 Include_test=0
178
SimpleInstall=1 SimpleInstallDescription="Just for me, no test suite."
180
(Note that omitting the launcher also omits file associations, and is only
181
recommended for per-user installs when there is also a system-wide installation
182
that included the launcher.)
184
The options listed above can also be provided in a file named ``unattend.xml``
185
alongside the executable. This file specifies a list of options and values.
186
When a value is provided as an attribute, it will be converted to a number if
187
possible. Values provided as element text are always left as strings. This
188
example file sets the same options and the previous example::
191
<Option Name="InstallAllUsers" Value="no" />
192
<Option Name="Include_launcher" Value="0" />
193
<Option Name="Include_test" Value="no" />
194
<Option Name="SimpleInstall" Value="yes" />
195
<Option Name="SimpleInstallDescription">Just for me, no test suite</Option>
198
.. _install-layout-option:
200
Installing Without Downloading
201
------------------------------
203
As some features of Python are not included in the initial installer download,
204
selecting those features may require an internet connection. To avoid this
205
need, all possible components may be downloaded on-demand to create a complete
206
*layout* that will no longer require an internet connection regardless of the
207
selected features. Note that this download may be bigger than required, but
208
where a large number of installations are going to be performed it is very
209
useful to have a locally cached copy.
211
Execute the following command from Command Prompt to download all possible
212
required files. Remember to substitute ``python-3.5.0.exe`` for the actual
213
name of your installer, and to create layouts in their own directories to
214
avoid collisions between files with the same name.
218
python-3.5.0.exe /layout [optional target directory]
220
You may also specify the ``/quiet`` option to hide the progress display.
225
Once Python has been installed, you can add or remove features through the
226
Programs and Features tool that is part of Windows. Select the Python entry and
227
choose "Uninstall/Change" to open the installer in maintenance mode.
229
"Modify" allows you to add or remove features by modifying the checkboxes -
230
unchanged checkboxes will not install or remove anything. Some options cannot be
231
changed in this mode, such as the install directory; to modify these, you will
232
need to remove and then reinstall Python completely.
234
"Repair" will verify all the files that should be installed using the current
235
settings and replace any that have been removed or modified.
237
"Uninstall" will remove Python entirely, with the exception of the
238
:ref:`launcher`, which has its own entry in Programs and Features.
243
With ongoing development of Python, some platforms that used to be supported
244
earlier are no longer supported (due to the lack of users or developers).
245
Check :pep:`11` for details on all unsupported platforms.
247
* `Windows CE <http://pythonce.sourceforge.net/>`_ is still supported.
248
* The `Cygwin <https://cygwin.com/>`_ installer offers to install the Python
249
interpreter as well (cf. `Cygwin package source
250
<ftp://ftp.uni-erlangen.de/pub/pc/gnuwin32/cygwin/mirrors/cygnus/
251
release/python>`_, `Maintainer releases
252
<http://www.tishler.net/jason/software/python/>`_)
254
See `Python for Windows <https://www.python.org/downloads/windows/>`_
255
for detailed information about platforms with pre-compiled installers.
259
`Python on XP <http://dooling.com/index.php/2006/03/14/python-on-xp-7-minutes-to-hello-world/>`_
260
"7 Minutes to "Hello World!""
261
by Richard Dooling, 2006
263
`Installing on Windows <http://www.diveintopython.net/installing_python/windows.html>`_
264
in "`Dive into Python: Python from novice to pro
265
<http://www.diveintopython.net/>`_"
266
by Mark Pilgrim, 2004,
269
`For Windows users <http://python.swaroopch.com/installation.html#installation-on-windows>`_
270
in "Installing Python"
271
in "`A Byte of Python <http://python.swaroopch.com/>`_"
278
Besides the standard CPython distribution, there are modified packages including
279
additional functionality. The following is a list of popular versions and their
282
`ActivePython <https://www.activestate.com/activepython/>`_
283
Installer with multi-platform compatibility, documentation, PyWin32
285
`Anaconda <https://www.continuum.io/downloads/>`_
286
Popular scientific modules (such as numpy, scipy and pandas) and the
287
``conda`` package manager.
289
`Canopy <https://www.enthought.com/products/canopy/>`_
290
A "comprehensive Python analysis environment" with editors and other
293
`WinPython <https://winpython.github.io/>`_
294
Windows-specific distribution with prebuilt scientific packages and
295
tools for building packages.
297
Note that these packages may not include the latest versions of Python or
298
other libraries, and are not maintained or supported by the core Python team.
305
To run Python conveniently from a command prompt, you might consider changing
306
some default environment variables in Windows. While the installer provides an
307
option to configure the PATH and PATHEXT variables for you, this is only
308
reliable for a single, system-wide installation. If you regularly use multiple
309
versions of Python, consider using the :ref:`launcher`.
314
Excursus: Setting environment variables
315
---------------------------------------
317
Windows allows environment variables to be configured permanently at both the
318
User level and the System level, or temporarily in a command prompt.
320
To temporarily set environment variables, open Command Prompt and use the
321
:command:`set` command::
323
C:\>set PATH=C:\Program Files\Python 3.5;%PATH%
324
C:\>set PYTHONPATH=%PYTHONPATH%;C:\My_python_lib
327
These changes will apply to any further commands executed in that console, and
328
will be inherited by any applications started from the console.
330
Including the variable name within percent signs will expand to the existing
331
value, allowing you to add your new value at either the start or the end.
332
Modifying :envvar:`PATH` by adding the directory containing
333
:program:`python.exe` to the start is a common way to ensure the correct version
334
of Python is launched.
336
To permanently modify the default environment variables, click Start and search
337
for 'edit environment variables', or open System properties, :guilabel:`Advanced
338
system settings` and click the :guilabel:`Environment Variables` button.
339
In this dialog, you can add or modify User and System variables. To change
340
System variables, you need non-restricted access to your machine
341
(i.e. Administrator rights).
345
Windows will concatenate User variables *after* System variables, which may
346
cause unexpected results when modifying :envvar:`PATH`.
348
The :envvar:`PYTHONPATH` variable is used by all versions of Python 2 and
349
Python 3, so you should not permanently configure this variable unless it
350
only includes code that is compatible with all of your installed Python
355
https://support.microsoft.com/kb/100843
356
Environment variables in Windows NT
358
https://technet.microsoft.com/en-us/library/cc754250.aspx
359
The SET command, for temporarily modifying environment variables
361
https://technet.microsoft.com/en-us/library/cc755104.aspx
362
The SETX command, for permanently modifying environment variables
364
https://support.microsoft.com/kb/310519
365
How To Manage Environment Variables in Windows XP
367
https://www.chem.gla.ac.uk/~louis/software/faq/q1.html
368
Setting Environment variables, Louis J. Farrugia
370
.. _windows-path-mod:
372
Finding the Python executable
373
-----------------------------
375
.. versionchanged:: 3.5
377
Besides using the automatically created start menu entry for the Python
378
interpreter, you might want to start Python in the command prompt. The
379
installer for Python 3.5 and later has an option to set that up for you.
381
On the first page of the installer, an option labelled "Add Python 3.5 to
382
PATH" can be selected to have the installer add the install location into the
383
:envvar:`PATH`. The location of the :file:`Scripts\\` folder is also added.
384
This allows you to type :command:`python` to run the interpreter, and
385
:command:`pip` for the package installer. Thus, you can also execute your
386
scripts with command line options, see :ref:`using-on-cmdline` documentation.
388
If you don't enable this option at install time, you can always re-run the
389
installer, select Modify, and enable it. Alternatively, you can manually
390
modify the :envvar:`PATH` using the directions in :ref:`setting-envvars`. You
391
need to set your :envvar:`PATH` environment variable to include the directory
392
of your Python installation, delimited by a semicolon from other entries. An
393
example variable could look like this (assuming the first two entries already
396
C:\WINDOWS\system32;C:\WINDOWS;C:\Program Files\Python 3.5
400
Python Launcher for Windows
401
===========================
403
.. versionadded:: 3.3
405
The Python launcher for Windows is a utility which aids in locating and
406
executing of different Python versions. It allows scripts (or the
407
command-line) to indicate a preference for a specific Python version, and
408
will locate and execute that version.
410
Unlike the :envvar:`PATH` variable, the launcher will correctly select the most
411
appropriate version of Python. It will prefer per-user installations over
412
system-wide ones, and orders by language version rather than using the most
413
recently installed version.
418
From the command-line
419
^^^^^^^^^^^^^^^^^^^^^
421
System-wide installations of Python 3.3 and later will put the launcher on your
422
:envvar:`PATH`. The launcher is compatible with all available versions of
423
Python, so it does not matter which version is installed. To check that the
424
launcher is available, execute the following command in Command Prompt:
430
You should find that the latest version of Python 2.x you have installed is
431
started - it can be exited as normal, and any additional command-line
432
arguments specified will be sent directly to Python.
434
If you have multiple versions of Python 2.x installed (e.g., 2.6 and 2.7) you
435
will have noticed that Python 2.7 was started - to launch Python 2.6, try the
442
If you have a Python 3.x installed, try the command:
448
You should find the latest version of Python 3.x starts.
450
If you see the following error, you do not have the launcher installed:
454
'py' is not recognized as an internal or external command,
455
operable program or batch file.
457
Per-user installations of Python do not add the launcher to :envvar:`PATH`
458
unless the option was selected on installation.
463
.. versionadded:: 3.5
465
If the launcher is run with no explicit Python version specification, and a
466
virtual environment (created with the standard library :mod:`venv` module or
467
the external ``virtualenv`` tool) active, the launcher will run the virtual
468
environment's interpreter rather than the global one. To run the global
469
interpreter, either deactivate the virtual environment, or explicitly specify
470
the global Python version.
475
Let's create a test Python script - create a file called ``hello.py`` with the
482
sys.stdout.write("hello from Python %s\n" % (sys.version,))
484
From the directory in which hello.py lives, execute the command:
490
You should notice the version number of your latest Python 2.x installation
491
is printed. Now try changing the first line to be:
497
Re-executing the command should now print the latest Python 3.x information.
498
As with the above command-line examples, you can specify a more explicit
499
version qualifier. Assuming you have Python 2.6 installed, try changing the
500
first line to ``#! python2.6`` and you should find the 2.6 version
503
From file associations
504
^^^^^^^^^^^^^^^^^^^^^^
506
The launcher should have been associated with Python files (i.e. ``.py``,
507
``.pyw``, ``.pyc`` files) when it was installed. This means that
508
when you double-click on one of these files from Windows explorer the launcher
509
will be used, and therefore you can use the same facilities described above to
510
have the script specify the version which should be used.
512
The key benefit of this is that a single launcher can support multiple Python
513
versions at the same time depending on the contents of the first line.
518
If the first line of a script file starts with ``#!``, it is known as a
519
"shebang" line. Linux and other Unix like operating systems have native
520
support for such lines and are commonly used on such systems to indicate how
521
a script should be executed. This launcher allows the same facilities to be
522
using with Python scripts on Windows and the examples above demonstrate their
525
To allow shebang lines in Python scripts to be portable between Unix and
526
Windows, this launcher supports a number of 'virtual' commands to specify
527
which interpreter to use. The supported virtual commands are:
529
* ``/usr/bin/env python``
530
* ``/usr/bin/python``
531
* ``/usr/local/bin/python``
534
For example, if the first line of your script starts with
540
The default Python will be located and used. As many Python scripts written
541
to work on Unix will already have this line, you should find these scripts can
542
be used by the launcher without modification. If you are writing a new script
543
on Windows which you hope will be useful on Unix, you should use one of the
544
shebang lines starting with ``/usr``.
546
Any of the above virtual commands can be suffixed with an explicit version
547
(either just the major version, or the major and minor version) - for example
548
``/usr/bin/python2.7`` - which will cause that specific version to be located
551
The ``/usr/bin/env`` form of shebang line has one further special property.
552
Before looking for installed Python interpreters, this form will search the
553
executable :envvar:`PATH` for a Python executable. This corresponds to the
554
behaviour of the Unix ``env`` program, which performs a :envvar:`PATH` search.
556
Arguments in shebang lines
557
--------------------------
559
The shebang lines can also specify additional options to be passed to the
560
Python interpreter. For example, if you have a shebang line:
564
#! /usr/bin/python -v
566
Then Python will be started with the ``-v`` option
571
Customization via INI files
572
^^^^^^^^^^^^^^^^^^^^^^^^^^^
574
Two .ini files will be searched by the launcher - ``py.ini`` in the current
575
user's "application data" directory (i.e. the directory returned by calling the
576
Windows function SHGetFolderPath with CSIDL_LOCAL_APPDATA) and ``py.ini`` in the
577
same directory as the launcher. The same .ini files are used for both the
578
'console' version of the launcher (i.e. py.exe) and for the 'windows' version
581
Customization specified in the "application directory" will have precedence over
582
the one next to the executable, so a user, who may not have write access to the
583
.ini file next to the launcher, can override commands in that global .ini file)
585
Customizing default Python versions
586
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
588
In some cases, a version qualifier can be included in a command to dictate
589
which version of Python will be used by the command. A version qualifier
590
starts with a major version number and can optionally be followed by a period
591
('.') and a minor version specifier. If the minor qualifier is specified, it
592
may optionally be followed by "-32" to indicate the 32-bit implementation of
593
that version be used.
595
For example, a shebang line of ``#!python`` has no version qualifier, while
596
``#!python3`` has a version qualifier which specifies only a major version.
598
If no version qualifiers are found in a command, the environment variable
599
``PY_PYTHON`` can be set to specify the default version qualifier - the default
600
value is "2". Note this value could specify just a major version (e.g. "2") or
601
a major.minor qualifier (e.g. "2.6"), or even major.minor-32.
603
If no minor version qualifiers are found, the environment variable
604
``PY_PYTHON{major}`` (where ``{major}`` is the current major version qualifier
605
as determined above) can be set to specify the full version. If no such option
606
is found, the launcher will enumerate the installed Python versions and use
607
the latest minor release found for the major version, which is likely,
608
although not guaranteed, to be the most recently installed version in that
611
On 64-bit Windows with both 32-bit and 64-bit implementations of the same
612
(major.minor) Python version installed, the 64-bit version will always be
613
preferred. This will be true for both 32-bit and 64-bit implementations of the
614
launcher - a 32-bit launcher will prefer to execute a 64-bit Python installation
615
of the specified version if available. This is so the behavior of the launcher
616
can be predicted knowing only what versions are installed on the PC and
617
without regard to the order in which they were installed (i.e., without knowing
618
whether a 32 or 64-bit version of Python and corresponding launcher was
619
installed last). As noted above, an optional "-32" suffix can be used on a
620
version specifier to change this behaviour.
624
* If no relevant options are set, the commands ``python`` and
625
``python2`` will use the latest Python 2.x version installed and
626
the command ``python3`` will use the latest Python 3.x installed.
628
* The commands ``python3.1`` and ``python2.7`` will not consult any
629
options at all as the versions are fully specified.
631
* If ``PY_PYTHON=3``, the commands ``python`` and ``python3`` will both use
632
the latest installed Python 3 version.
634
* If ``PY_PYTHON=3.1-32``, the command ``python`` will use the 32-bit
635
implementation of 3.1 whereas the command ``python3`` will use the latest
636
installed Python (PY_PYTHON was not considered at all as a major
637
version was specified.)
639
* If ``PY_PYTHON=3`` and ``PY_PYTHON3=3.1``, the commands
640
``python`` and ``python3`` will both use specifically 3.1
642
In addition to environment variables, the same settings can be configured
643
in the .INI file used by the launcher. The section in the INI file is
644
called ``[defaults]`` and the key name will be the same as the
645
environment variables without the leading ``PY_`` prefix (and note that
646
the key names in the INI file are case insensitive.) The contents of
647
an environment variable will override things specified in the INI file.
651
* Setting ``PY_PYTHON=3.1`` is equivalent to the INI file containing:
658
* Setting ``PY_PYTHON=3`` and ``PY_PYTHON3=3.1`` is equivalent to the INI file
670
If an environment variable ``PYLAUNCH_DEBUG`` is set (to any value), the
671
launcher will print diagnostic information to stderr (i.e. to the console).
672
While this information manages to be simultaneously verbose *and* terse, it
673
should allow you to see what versions of Python were located, why a
674
particular version was chosen and the exact command-line used to execute the
684
Python usually stores its library (and thereby your site-packages folder) in the
685
installation directory. So, if you had installed Python to
686
:file:`C:\\Python\\`, the default library would reside in
687
:file:`C:\\Python\\Lib\\` and third-party modules should be stored in
688
:file:`C:\\Python\\Lib\\site-packages\\`.
690
This is how :data:`sys.path` is populated on Windows:
692
* An empty entry is added at the start, which corresponds to the current
695
* If the environment variable :envvar:`PYTHONPATH` exists, as described in
696
:ref:`using-on-envvars`, its entries are added next. Note that on Windows,
697
paths in this variable must be separated by semicolons, to distinguish them
698
from the colon used in drive identifiers (``C:\`` etc.).
700
* Additional "application paths" can be added in the registry as subkeys of
701
:samp:`\\SOFTWARE\\Python\\PythonCore\\{version}\\PythonPath` under both the
702
``HKEY_CURRENT_USER`` and ``HKEY_LOCAL_MACHINE`` hives. Subkeys which have
703
semicolon-delimited path strings as their default value will cause each path
704
to be added to :data:`sys.path`. (Note that all known installers only use
705
HKLM, so HKCU is typically empty.)
707
* If the environment variable :envvar:`PYTHONHOME` is set, it is assumed as
708
"Python Home". Otherwise, the path of the main Python executable is used to
709
locate a "landmark file" (``Lib\os.py``) to deduce the "Python Home". If a
710
Python home is found, the relevant sub-directories added to :data:`sys.path`
711
(``Lib``, ``plat-win``, etc) are based on that folder. Otherwise, the core
712
Python path is constructed from the PythonPath stored in the registry.
714
* If the Python Home cannot be located, no :envvar:`PYTHONPATH` is specified in
715
the environment, and no registry entries can be found, a default path with
716
relative entries is used (e.g. ``.\Lib;.\plat-win``, etc).
718
If a ``pyvenv.cfg`` file is found alongside the main executable or in the
719
directory one level above the executable, the following variations apply:
721
* If ``home`` is an absolute path and :envvar:`PYTHONHOME` is not set, this
722
path is used instead of the path to the main executable when deducing the
725
* If ``applocal`` is set to true, the ``home`` property or the main executable
726
is always used as the home path, and all environment variables or registry
727
values affecting the path are ignored. The landmark file is not checked.
729
The end result of all this is:
731
* When running :file:`python.exe`, or any other .exe in the main Python
732
directory (either an installed version, or directly from the PCbuild
733
directory), the core path is deduced, and the core paths in the registry are
734
ignored. Other "application paths" in the registry are always read.
736
* When Python is hosted in another .exe (different directory, embedded via COM,
737
etc), the "Python Home" will not be deduced, so the core path from the
738
registry is used. Other "application paths" in the registry are always read.
740
* If Python can't find its home and there are no registry value (frozen .exe,
741
some very strange installation setup) you get a path with some default, but
744
For those who want to bundle Python into their application or distribution, the
745
following advice will prevent conflicts with other installations:
747
* Include a ``pyvenv.cfg`` file alongside your executable containing
748
``applocal = true``. This will ensure that your own directory will be used to
749
resolve paths even if you have included the standard library in a ZIP file.
750
It will also ignore user site-packages and other paths listed in the
753
* If you are loading :file:`python3.dll` or :file:`python35.dll` in your own
754
executable, explicitly call :c:func:`Py_SetPath` or (at least)
755
:c:func:`Py_SetProgramName` before :c:func:`Py_Initialize`.
757
* Clear and/or overwrite :envvar:`PYTHONPATH` and set :envvar:`PYTHONHOME`
758
before launching :file:`python.exe` from your application.
760
* If you cannot use the previous suggestions (for example, you are a
761
distribution that allows people to run :file:`python.exe` directly), ensure
762
that the landmark file (:file:`Lib\\os.py`) exists in your install directory.
763
(Note that it will not be detected inside a ZIP file.)
765
These will ensure that the files in a system-wide installation will not take
766
precedence over the copy of the standard library bundled with your application.
767
Otherwise, your users may experience problems using your application. Note that
768
the first suggestion is the best, as the other may still be susceptible to
769
non-standard paths in the registry and user site-packages.
774
Even though Python aims to be portable among all platforms, there are features
775
that are unique to Windows. A couple of modules, both in the standard library
776
and external, and snippets exist to use these features.
778
The Windows-specific standard modules are documented in
779
:ref:`mswin-specific-services`.
784
The `PyWin32 <https://pypi.python.org/pypi/pywin32>`_ module by Mark Hammond
785
is a collection of modules for advanced Windows-specific support. This includes
788
* `Component Object Model <https://www.microsoft.com/com/>`_ (COM)
792
* `Microsoft Foundation Classes <https://msdn.microsoft.com/en-us/library/fe1cf721%28VS.80%29.aspx>`_ (MFC)
795
`PythonWin <https://web.archive.org/web/20060524042422/
796
https://www.python.org/windows/pythonwin/>`_ is a sample MFC application
797
shipped with PyWin32. It is an embeddable IDE with a built-in debugger.
801
`Win32 How Do I...? <http://timgolden.me.uk/python/win32_how_do_i.html>`_
804
`Python and COM <http://www.boddie.org.uk/python/COM.html>`_
805
by David and Paul Boddie
811
`cx_Freeze <http://cx-freeze.sourceforge.net/>`_ is a :mod:`distutils`
812
extension (see :ref:`extending-distutils`) which wraps Python scripts into
813
executable Windows programs (:file:`{*}.exe` files). When you have done this,
814
you can distribute your application without requiring your users to install
821
Since Python's advanced terminal handling layer, :mod:`curses`, is restricted to
822
Unix-like systems, there is a library exclusive to Windows as well: Windows
823
Console I/O for Python.
825
`WConio <http://newcenturycomputers.net/projects/wconio.html>`_ is a wrapper for
826
Turbo-C's :file:`CONIO.H`, used to create text user interfaces.
830
Compiling Python on Windows
831
===========================
833
If you want to compile CPython yourself, first thing you should do is get the
834
`source <https://www.python.org/downloads/source/>`_. You can download either the
835
latest release's source or just grab a fresh `checkout
836
<https://docs.python.org/devguide/setup.html#getting-the-source-code>`_.
838
The source tree contains a build solution and project files for Microsoft
839
Visual Studio 2015, which is the compiler used to build the official Python
840
releases. These files are in the :file:`PCbuild` directory.
842
Check :file:`PCbuild/readme.txt` for general information on the build process.
845
For extension modules, consult :ref:`building-on-windows`.
849
`Python + Windows + distutils + SWIG + gcc MinGW <http://sebsauvage.net/python/mingw.html>`_
850
or "Creating Python extensions in C/C++ with SWIG and compiling them with
851
MinGW gcc under Windows" or "Installing Python extension with distutils
852
and without Microsoft Visual C++" by Sébastien Sauvage, 2003
854
`MingW -- Python extensions <http://oldwiki.mingw.org/index.php/Python%20extensions>`_
855
by Trent Apted et al, 2007
858
Embedded Distribution
859
=====================
861
.. versionadded:: 3.5
863
The embedded distribution is a ZIP file containing a minimal Python environment.
864
It is intended for acting as part of another application, rather than being
865
directly accessed by end-users.
867
When extracted, the embedded distribution is (almost) fully isolated from the
868
user's system, including environment variables, system registry settings, and
869
installed packages. The standard library is included as pre-compiled and
870
optimized ``.pyc`` files in a ZIP, and ``python3.dll``, ``python35.dll``,
871
``python.exe`` and ``pythonw.exe`` are all provided. Tcl/tk (including all
872
dependants, such as Idle), pip and the Python documentation are not included.
876
The embedded distribution does not include the `Microsoft C Runtime
877
<https://www.microsoft.com/en-us/download/details.aspx?id=48145>`_ and it is
878
the responsibility of the application installer to provide this. The
879
runtime may have already been installed on a user's system previously or
880
automatically via Windows Update, and can be detected by finding
881
``ucrtbase.dll`` in the system directory.
883
Third-party packages should be installed by the application installer alongside
884
the embedded distribution. Using pip to manage dependencies as for a regular
885
Python installation is not supported with this distribution, though with some
886
care it may be possible to include and use pip for automatic updates. In
887
general, third-party packages should be treated as part of the application
888
("vendoring") so that the developer can ensure compatibility with newer
889
versions before providing updates to users.
891
The two recommended use cases for this distribution are described below.
896
An application written in Python does not necessarily require users to be aware
897
of that fact. The embedded distribution may be used in this case to include a
898
private version of Python in an install package. Depending on how transparent it
899
should be (or conversely, how professional it should appear), there are two
902
Using a specialized executable as a launcher requires some coding, but provides
903
the most transparent experience for users. With a customized launcher, there are
904
no obvious indications that the program is running on Python: icons can be
905
customized, company and version information can be specified, and file
906
associations behave properly. In most cases, a custom launcher should simply be
907
able to call ``Py_Main`` with a hard-coded command line.
909
The simpler approach is to provide a batch file or generated shortcut that
910
directly calls the ``python.exe`` or ``pythonw.exe`` with the required
911
command-line arguments. In this case, the application will appear to be Python
912
and not its actual name, and users may have trouble distinguishing it from other
913
running Python processes or file associations.
915
With the latter approach, packages should be installed as directories alongside
916
the Python executable to ensure they are available on the path. With the
917
specialized launcher, packages can be located in other locations as there is an
918
opportunity to specify the search path before launching the application.
923
Applications written in native code often require some form of scripting
924
language, and the embedded Python distribution can be used for this purpose. In
925
general, the majority of the application is in native code, and some part will
926
either invoke ``python.exe`` or directly use ``python3.dll``. For either case,
927
extracting the embedded distribution to a subdirectory of the application
928
installation is sufficient to provide a loadable Python interpreter.
930
As with the application use, packages can be installed to any location as there
931
is an opportunity to specify search paths before initializing the interpreter.
932
Otherwise, there is no fundamental differences between using the embedded
933
distribution and a regular installation.
940
`Python Programming On Win32 <http://shop.oreilly.com/product/9781565926219.do>`_
941
"Help for Windows Programmers"
942
by Mark Hammond and Andy Robinson, O'Reilly Media, 2000,
945
`A Python for Windows Tutorial <http://www.imladris.com/Scripts/PythonForWindows.html>`_
946
by Amanda Birmingham, 2004
948
:pep:`397` - Python launcher for Windows
949
The proposal for the launcher to be included in the Python distribution.
added
removed
python-3.5.2-docs-html/_sources/using/windows.txt
