Lines Matching +full:python +full:- +full:version
3 .. _using-on-windows:
6 Using Python on Windows
12 This document aims to give an overview of Windows-specific behaviour you should
13 know about when using Python on Microsoft Windows.
16 supported installation of Python. To make Python available, the CPython team
18 <https://www.python.org/download/releases/>`_ for many years. These installers
19 are primarily intended to add a per-user installation of Python, with the
22 available for application-local distributions.
24 As specified in :pep:`11`, a Python release only supports a Windows platform
26 Python |version| supports Windows Vista and newer. If you require Windows XP
27 support then please install Python 3.4.
32 :ref:`windows-full` contains all components and is the best option for
33 developers using Python for any kind of project.
35 :ref:`windows-store` is a simple installation of Python that is suitable for
38 programs. It also provides many convenient commands for launching Python and
41 :ref:`windows-nuget` are lightweight installations intended for continuous
42 integration systems. It can be used to build Python packages or run scripts,
45 :ref:`windows-embeddable` is a minimal package of Python suitable for
49 .. _windows-full:
55 ------------------
57 Four Python |version| installers are available for download - two each for the
58 32-bit and 64-bit versions of the interpreter. The *web installer* is a small
62 features. See :ref:`install-layout-option` for other ways to avoid downloading
74 * Python will be installed into your user directory
82 install, the installation location and other options or post-install actions.
85 To perform an all-users installation, you should select "Customize
89 * Python will be installed into the Program Files directory
92 * The standard library can be pre-compiled to bytecode
96 .. _max-path:
99 --------------------------------
117 Support for long paths was enabled in Python.
119 .. _install-quiet-option:
122 ---------------------
129 To completely hide the installer UI and install Python silently, pass the
132 option may be passed to immediately begin removing Python - no prompt will be
139 +---------------------------+--------------------------------------+--------------------------+
142 | InstallAllUsers | Perform a system-wide installation. | 0 |
143 +---------------------------+--------------------------------------+--------------------------+
146 +---------------------------+--------------------------------------+--------------------------+
148 | | for all-user installs | Python X.Y` or :file:`\ |
150 | | | Python X.Y` |
151 +---------------------------+--------------------------------------+--------------------------+
153 | | just-for-me installs | Programs\\PythonXY` or |
155 | | | Programs\\PythonXY-32` or|
157 | | | Programs\\PythonXY-64` |
158 +---------------------------+--------------------------------------+--------------------------+
161 +---------------------------+--------------------------------------+--------------------------+
164 +---------------------------+--------------------------------------+--------------------------+
167 +---------------------------+--------------------------------------+--------------------------+
171 +---------------------------+--------------------------------------+--------------------------+
174 +---------------------------+--------------------------------------+--------------------------+
175 | Include_doc | Install Python manual | 1 |
176 +---------------------------+--------------------------------------+--------------------------+
178 +---------------------------+--------------------------------------+--------------------------+
181 +---------------------------+--------------------------------------+--------------------------+
182 | Include_exe | Install :file:`python.exe` and | 1 |
184 +---------------------------+--------------------------------------+--------------------------+
186 +---------------------------+--------------------------------------+--------------------------+
189 +---------------------------+--------------------------------------+--------------------------+
192 +---------------------------+--------------------------------------+--------------------------+
194 +---------------------------+--------------------------------------+--------------------------+
196 +---------------------------+--------------------------------------+--------------------------+
198 +---------------------------+--------------------------------------+--------------------------+
200 +---------------------------+--------------------------------------+--------------------------+
202 +---------------------------+--------------------------------------+--------------------------+
205 +---------------------------+--------------------------------------+--------------------------+
207 +---------------------------+--------------------------------------+--------------------------+
210 +---------------------------+--------------------------------------+--------------------------+
212 For example, to silently install a default, system-wide Python installation,
215 python-3.8.0.exe /quiet InstallAllUsers=1 PrependPath=1 Include_test=0
217 To allow users to easily install a personal copy of Python without the test
221 python-3.8.0.exe InstallAllUsers=0 Include_launcher=0 Include_test=0
225 recommended for per-user installs when there is also a system-wide installation
234 .. code-block:: xml
244 .. _install-layout-option:
247 ------------------------------
249 As some features of Python are not included in the initial installer download,
251 need, all possible components may be downloaded on-demand to create a complete
258 required files. Remember to substitute ``python-3.8.0.exe`` for the actual
264 python-3.8.0.exe /layout [optional target directory]
269 --------------------
271 Once Python has been installed, you can add or remove features through the
272 Programs and Features tool that is part of Windows. Select the Python entry and
275 "Modify" allows you to add or remove features by modifying the checkboxes -
278 need to remove and then reinstall Python completely.
283 "Uninstall" will remove Python entirely, with the exception of the
287 .. _windows-store:
294 The Microsoft Store package is an easily installable Python interpreter that
298 search the Microsoft Store app for "Python |version|". Ensure that the app
299 you select is published by the Python Software Foundation, and install it.
302 Python will always be available for free on the Microsoft Store. If you
305 After installation, Python may be launched by finding it in Start.
307 session by typing ``python``. Further, pip and IDLE may be used by typing
310 All three commands are also available with version number suffixes, for
312 ``python.exe`` (where ``3.x`` is the specific version you want to launch,
313 such as |version|). Open "Manage App Execution Aliases" through Start to
314 select which version of Python is associated with each command. It is
316 whichever version of ``python`` is selected.
318 Virtual environments can be created with ``python -m venv`` and activated
321 If you have installed another version of Python and added it to your
322 ``PATH`` variable, it will be available as ``python.exe`` rather than the
326 The ``py.exe`` launcher will detect this Python installation, but will prefer
329 To remove Python, open Settings and use Apps and Features, or else find
330 Python in Start and right-click to select Uninstall. Uninstalling will
331 remove all packages you installed directly into this Python installation, but
335 ------------
337 Because of restrictions on Microsoft Store apps, Python scripts may not have
343 .. _windows-nuget:
350 The nuget.org package is a reduced size Python environment intended for use on
351 continuous integration and build systems that do not have a system-wide
352 install of Python. While nuget is "the package manager for .NET", it also works
353 perfectly fine for packages containing build-time tools.
355 Visit `nuget.org <https://www.nuget.org/>`_ for the most up-to-date information
356 on using nuget. What follows is a summary that is sufficient for Python
361 tool, the latest version of Python for 64-bit or 32-bit machines is installed
364 nuget.exe install python -ExcludeVersion -OutputDirectory .
365 nuget.exe install pythonx86 -ExcludeVersion -OutputDirectory .
367 To select a particular version, add a ``-Version 3.x.y``. The output directory
370 and without the ``-ExcludeVersion`` option this name will include the specific
371 version installed. Inside the subdirectory is a ``tools`` directory that
372 contains the Python installation::
374 # Without -ExcludeVersion
375 > .\python.3.5.2\tools\python.exe -V
376 Python 3.5.2
378 # With -ExcludeVersion
379 > .\python\tools\python.exe -V
380 Python 3.5.2
383 installed side-by-side and referenced using the full path. Alternatively,
388 contains a MSBuild properties file ``python.props`` that can be used in a
389 C++ project to reference the Python install. Including the settings will
393 `www.nuget.org/packages/python <https://www.nuget.org/packages/python>`_
394 for the 64-bit version and `www.nuget.org/packages/pythonx86
395 <https://www.nuget.org/packages/pythonx86>`_ for the 32-bit version.
398 .. _windows-embeddable:
405 The embedded distribution is a ZIP file containing a minimal Python environment.
407 directly accessed by end-users.
411 installed packages. The standard library is included as pre-compiled and
413 ``python.exe`` and ``pythonw.exe`` are all provided. Tcl/tk (including all
414 dependants, such as Idle), pip and the Python documentation are not included.
419 <https://www.microsoft.com/en-us/download/details.aspx?id=48145>`_ and it is
425 Third-party packages should be installed by the application installer alongside
427 Python installation is not supported with this distribution, though with some
429 general, third-party packages should be treated as part of the application
435 Python Application
436 ------------------
438 An application written in Python does not necessarily require users to be aware
440 private version of Python in an install package. Depending on how transparent it
446 no obvious indications that the program is running on Python: icons can be
447 customized, company and version information can be specified, and file
449 able to call ``Py_Main`` with a hard-coded command line.
452 directly calls the ``python.exe`` or ``pythonw.exe`` with the required
453 command-line arguments. In this case, the application will appear to be Python
455 running Python processes or file associations.
458 the Python executable to ensure they are available on the path. With the
462 Embedding Python
463 ----------------
466 language, and the embedded Python distribution can be used for this purpose. In
468 either invoke ``python.exe`` or directly use ``python3.dll``. For either case,
470 installation is sufficient to provide a loadable Python interpreter.
486 Installer with multi-platform compatibility, documentation, PyWin32
493 A "comprehensive Python analysis environment" with editors and other
497 Windows-specific distribution with prebuilt scientific packages and
500 Note that these packages may not include the latest versions of Python or
501 other libraries, and are not maintained or supported by the core Python team.
505 Configuring Python
508 To run Python conveniently from a command prompt, you might consider changing
511 reliable for a single, system-wide installation. If you regularly use multiple
512 versions of Python, consider using the :ref:`launcher`.
515 .. _setting-envvars:
518 ---------------------------------------
526 .. code-block:: doscon
528 C:\>set PATH=C:\Program Files\Python 3.8;%PATH%
530 C:\>python
538 :program:`python.exe` to the start is a common way to ensure the correct version
539 of Python is launched.
545 System variables, you need non-restricted access to your machine
553 The :envvar:`PYTHONPATH` variable is used by all versions of Python 2 and
554 Python 3, so you should not permanently configure this variable unless it
555 only includes code that is compatible with all of your installed Python
560 https://www.microsoft.com/en-us/wdsi/help/folder-variables
563 https://technet.microsoft.com/en-us/library/cc754250.aspx
566 https://technet.microsoft.com/en-us/library/cc755104.aspx
569 … https://support.microsoft.com/en-us/help/310519/how-to-manage-environment-variables-in-windows-xp
575 .. _windows-path-mod:
577 Finding the Python executable
578 -----------------------------
582 Besides using the automatically created start menu entry for the Python
583 interpreter, you might want to start Python in the command prompt. The
586 On the first page of the installer, an option labelled "Add Python to PATH"
589 This allows you to type :command:`python` to run the interpreter, and
591 scripts with command line options, see :ref:`using-on-cmdline` documentation.
593 If you don't enable this option at install time, you can always re-run the
595 modify the :envvar:`PATH` using the directions in :ref:`setting-envvars`. You
597 of your Python installation, delimited by a semicolon from other entries. An
601 C:\WINDOWS\system32;C:\WINDOWS;C:\Program Files\Python 3.8
603 .. _win-utf8-mode:
605 UTF-8 mode
611 Page). Python uses it for the default encoding of text files (e.g.
614 This may cause issues because UTF-8 is widely used on the internet
617 You can use UTF-8 mode to change the default text encoding to UTF-8.
618 You can enable UTF-8 mode via the ``-X utf8`` command line option, or
620 enabling UTF-8 mode, and :ref:`setting-envvars` for how to modify
623 When UTF-8 mode is enabled:
625 * :func:`locale.getpreferredencoding` returns ``'UTF-8'`` instead of
630 all use UTF-8 as their text encoding.
634 will affect all Python 3.7+ applications on your system.
635 If you have any Python 3.7+ applications which rely on the legacy
637 temporarily or use the ``-X utf8`` command line option.
640 Even when UTF-8 mode is disabled, Python uses UTF-8 by default
649 Python Launcher for Windows
654 The Python launcher for Windows is a utility which aids in locating and
655 executing of different Python versions. It allows scripts (or the
656 command-line) to indicate a preference for a specific Python version, and
657 will locate and execute that version.
660 appropriate version of Python. It will prefer per-user installations over
661 system-wide ones, and orders by language version rather than using the most
662 recently installed version.
667 ---------------
669 From the command-line
674 System-wide installations of Python 3.3 and later will put the launcher on your
676 Python, so it does not matter which version is installed. To check that the
683 You should find that the latest version of Python you have installed is
684 started - it can be exited as normal, and any additional command-line
685 arguments specified will be sent directly to Python.
687 If you have multiple versions of Python installed (e.g., 2.7 and |version|) you
688 will have noticed that Python |version| was started - to launch Python 2.7, try
693 py -2.7
695 If you want the latest version of Python 2.x you have installed, try the
700 py -2
702 You should find the latest version of Python 2.x starts.
711 Per-user installations of Python do not add the launcher to :envvar:`PATH`
719 If the launcher is run with no explicit Python version specification, and a
724 the global Python version.
729 Let's create a test Python script - create a file called ``hello.py`` with the
732 .. code-block:: python
734 #! python
736 sys.stdout.write("hello from Python %s\n" % (sys.version,))
744 You should notice the version number of your latest Python 2.x installation
747 .. code-block:: python
751 Re-executing the command should now print the latest Python 3.x information.
752 As with the above command-line examples, you can specify a more explicit
753 version qualifier. Assuming you have Python 2.6 installed, try changing the
754 first line to ``#! python2.6`` and you should find the 2.6 version
757 Note that unlike interactive use, a bare "python" will use the latest
758 version of Python 2.x that you have installed. This is for backward
759 compatibility and for compatibility with Unix, where the command ``python``
760 typically refers to Python 2.
765 The launcher should have been associated with Python files (i.e. ``.py``,
767 when you double-click on one of these files from Windows explorer the launcher
769 have the script specify the version which should be used.
771 The key benefit of this is that a single launcher can support multiple Python
775 -------------
781 be used with Python scripts on Windows and the examples above demonstrate their
784 To allow shebang lines in Python scripts to be portable between Unix and
788 * ``/usr/bin/env python``
789 * ``/usr/bin/python``
790 * ``/usr/local/bin/python``
791 * ``python``
795 .. code-block:: sh
797 #! /usr/bin/python
799 The default Python will be located and used. As many Python scripts written
805 Any of the above virtual commands can be suffixed with an explicit version
806 (either just the major version, or the major and minor version).
807 Furthermore the 32-bit version can be requested by adding "-32" after the
808 minor version. I.e. ``/usr/bin/python2.7-32`` will request usage of the
809 32-bit python 2.7.
813 Beginning with python launcher 3.7 it is possible to request 64-bit version
814 by the "-64" suffix. Furthermore it is possible to specify a major and
815 architecture without minor (i.e. ``/usr/bin/python3-64``).
818 Before looking for installed Python interpreters, this form will search the
819 executable :envvar:`PATH` for a Python executable. This corresponds to the
823 --------------------------
826 Python interpreter. For example, if you have a shebang line:
828 .. code-block:: sh
830 #! /usr/bin/python -v
832 Then Python will be started with the ``-v`` option
835 -------------
840 Two .ini files will be searched by the launcher - ``py.ini`` in the current
844 'console' version of the launcher (i.e. py.exe) and for the 'windows' version
851 Customizing default Python versions
854 In some cases, a version qualifier can be included in a command to dictate
855 which version of Python will be used by the command. A version qualifier
856 starts with a major version number and can optionally be followed by a period
857 ('.') and a minor version specifier. Furthermore it is possible to specify
858 if a 32 or 64 bit implementation shall be requested by adding "-32" or "-64".
860 For example, a shebang line of ``#!python`` has no version qualifier, while
861 ``#!python3`` has a version qualifier which specifies only a major version.
863 If no version qualifiers are found in a command, the environment
864 variable :envvar:`PY_PYTHON` can be set to specify the default version
867 "3.7", "3.7-32" or "3.7-64". (Note that the "-64" option is only
868 available with the launcher included with Python 3.7 or newer.)
870 If no minor version qualifiers are found, the environment variable
871 ``PY_PYTHON{major}`` (where ``{major}`` is the current major version qualifier
872 as determined above) can be set to specify the full version. If no such option
873 is found, the launcher will enumerate the installed Python versions and use
874 the latest minor release found for the major version, which is likely,
875 although not guaranteed, to be the most recently installed version in that
878 On 64-bit Windows with both 32-bit and 64-bit implementations of the same
879 (major.minor) Python version installed, the 64-bit version will always be
880 preferred. This will be true for both 32-bit and 64-bit implementations of the
881 launcher - a 32-bit launcher will prefer to execute a 64-bit Python installation
882 of the specified version if available. This is so the behavior of the launcher
885 whether a 32 or 64-bit version of Python and corresponding launcher was
886 installed last). As noted above, an optional "-32" or "-64" suffix can be
887 used on a version specifier to change this behaviour.
891 * If no relevant options are set, the commands ``python`` and
892 ``python2`` will use the latest Python 2.x version installed and
893 the command ``python3`` will use the latest Python 3.x installed.
898 * If ``PY_PYTHON=3``, the commands ``python`` and ``python3`` will both use
899 the latest installed Python 3 version.
901 * If ``PY_PYTHON=3.1-32``, the command ``python`` will use the 32-bit
903 installed Python (PY_PYTHON was not considered at all as a major
904 version was specified.)
907 ``python`` and ``python3`` will both use specifically 3.1
920 .. code-block:: ini
923 python=3.1
928 .. code-block:: ini
931 python=3
935 -----------
940 should allow you to see what versions of Python were located, why a
941 particular version was chosen and the exact command-line used to execute the
942 target Python.
951 Python usually stores its library (and thereby your site-packages folder) in the
952 installation directory. So, if you had installed Python to
953 :file:`C:\\Python\\`, the default library would reside in
954 :file:`C:\\Python\\Lib\\` and third-party modules should be stored in
955 :file:`C:\\Python\\Lib\\site-packages\\`.
958 name as the DLL (``python37._pth``) or the executable (``python._pth``) and
980 :ref:`using-on-envvars`, its entries are added next. Note that on Windows,
985 :samp:`\\SOFTWARE\\Python\\PythonCore\\{version}\\PythonPath` under both the
987 semicolon-delimited path strings as their default value will cause each path
992 "Python Home". Otherwise, the path of the main Python executable is used to
994 the "Python Home". If a Python home is found, the relevant sub-directories
995 added to :data:`sys.path` (``Lib``, ``plat-win``, etc) are based on that
996 folder. Otherwise, the core Python path is constructed from the PythonPath
999 * If the Python Home cannot be located, no :envvar:`PYTHONPATH` is specified in
1001 relative entries is used (e.g. ``.\Lib;.\plat-win``, etc).
1012 * When running :file:`python.exe`, or any other .exe in the main Python
1013 directory (either an installed version, or directly from the PCbuild
1017 * When Python is hosted in another .exe (different directory, embedded via COM,
1018 etc), the "Python Home" will not be deduced, so the core path from the
1021 * If Python can't find its home and there are no registry value (frozen .exe,
1025 For those who want to bundle Python into their application or distribution, the
1038 before launching :file:`python.exe` from your application.
1041 distribution that allows people to run :file:`python.exe` directly), ensure
1046 These will ensure that the files in a system-wide installation will not take
1050 non-standard paths in the registry and user site-packages.
1071 Even though Python aims to be portable among all platforms, there are features
1075 The Windows-specific standard modules are documented in
1076 :ref:`mswin-specific-services`.
1079 -------
1082 is a collection of modules for advanced Windows-specific support. This includes
1086 <https://docs.microsoft.com/en-us/windows/desktop/com/component-object-model--com--portal>`_
1091 * `Microsoft Foundation Classes <https://msdn.microsoft.com/en-us/library/fe1cf721%28VS.80%29.aspx>…
1095 https://www.python.org/windows/pythonwin/>`_ is a sample MFC application
1096 shipped with PyWin32. It is an embeddable IDE with a built-in debugger.
1100 `Win32 How Do I...? <http://timgolden.me.uk/python/win32_how_do_i.html>`_
1103 `Python and COM <http://www.boddie.org.uk/python/COM.html>`_
1108 ---------
1110 `cx_Freeze <https://anthony-tuininga.github.io/cx_Freeze/>`_ is a :mod:`distutils`
1111 extension (see :ref:`extending-distutils`) which wraps Python scripts into
1114 Python.
1118 ------
1120 Since Python's advanced terminal handling layer, :mod:`curses`, is restricted to
1121 Unix-like systems, there is a library exclusive to Windows as well: Windows
1122 Console I/O for Python.
1125 Turbo-C's :file:`CONIO.H`, used to create text user interfaces.
1129 Compiling Python on Windows
1133 `source <https://www.python.org/downloads/source/>`_. You can download either the
1135 <https://devguide.python.org/setup/#getting-the-source-code>`_.
1138 Visual Studio 2015, which is the compiler used to build the official Python
1144 For extension modules, consult :ref:`building-on-windows`.
1148 `Python + Windows + distutils + SWIG + gcc MinGW <http://sebsauvage.net/python/mingw.html>`_
1149 or "Creating Python extensions in C/C++ with SWIG and compiling them with
1150 MinGW gcc under Windows" or "Installing Python extension with distutils
1153 `MingW -- Python extensions <http://www.mingw.org/wiki/FAQ#toc14>`_
1159 With ongoing development of Python, some platforms that used to be supported
1164 * The `Cygwin <https://cygwin.com/>`_ installer offers to install the Python
1166 <ftp://ftp.uni-erlangen.de/pub/pc/gnuwin32/cygwin/mirrors/cygnus/
1167 release/python>`_, `Maintainer releases
1168 <http://www.tishler.net/jason/software/python/>`_)
1170 See `Python for Windows <https://www.python.org/downloads/windows/>`_
1171 for detailed information about platforms with pre-compiled installers.