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 8.1 and newer. If you require Windows 7
27 support, please install Python 3.8.
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.9.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.9.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.9.0.exe`` for the actual
264 python-3.9.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 Microsoft's documentation on packaged full-trust apps, currently available at
344 `docs.microsoft.com/en-us/windows/msix/desktop/desktop-to-uwp-behind-the-scenes
345 <https://docs.microsoft.com/en-us/windows/msix/desktop/desktop-to-uwp-behind-the-scenes>`_
348 .. _windows-nuget:
355 The nuget.org package is a reduced size Python environment intended for use on
356 continuous integration and build systems that do not have a system-wide
357 install of Python. While nuget is "the package manager for .NET", it also works
358 perfectly fine for packages containing build-time tools.
360 Visit `nuget.org <https://www.nuget.org/>`_ for the most up-to-date information
361 on using nuget. What follows is a summary that is sufficient for Python
366 tool, the latest version of Python for 64-bit or 32-bit machines is installed
369 nuget.exe install python -ExcludeVersion -OutputDirectory .
370 nuget.exe install pythonx86 -ExcludeVersion -OutputDirectory .
372 To select a particular version, add a ``-Version 3.x.y``. The output directory
375 and without the ``-ExcludeVersion`` option this name will include the specific
376 version installed. Inside the subdirectory is a ``tools`` directory that
377 contains the Python installation::
379 # Without -ExcludeVersion
380 > .\python.3.5.2\tools\python.exe -V
381 Python 3.5.2
383 # With -ExcludeVersion
384 > .\python\tools\python.exe -V
385 Python 3.5.2
388 installed side-by-side and referenced using the full path. Alternatively,
393 contains a MSBuild properties file ``python.props`` that can be used in a
394 C++ project to reference the Python install. Including the settings will
398 `www.nuget.org/packages/python <https://www.nuget.org/packages/python>`_
399 for the 64-bit version and `www.nuget.org/packages/pythonx86
400 <https://www.nuget.org/packages/pythonx86>`_ for the 32-bit version.
403 .. _windows-embeddable:
410 The embedded distribution is a ZIP file containing a minimal Python environment.
412 directly accessed by end-users.
416 installed packages. The standard library is included as pre-compiled and
418 ``python.exe`` and ``pythonw.exe`` are all provided. Tcl/tk (including all
419 dependants, such as Idle), pip and the Python documentation are not included.
424 <https://www.microsoft.com/en-us/download/details.aspx?id=48145>`_ and it is
430 Third-party packages should be installed by the application installer alongside
432 Python installation is not supported with this distribution, though with some
434 general, third-party packages should be treated as part of the application
440 Python Application
441 ------------------
443 An application written in Python does not necessarily require users to be aware
445 private version of Python in an install package. Depending on how transparent it
451 no obvious indications that the program is running on Python: icons can be
452 customized, company and version information can be specified, and file
454 able to call ``Py_Main`` with a hard-coded command line.
457 directly calls the ``python.exe`` or ``pythonw.exe`` with the required
458 command-line arguments. In this case, the application will appear to be Python
460 running Python processes or file associations.
463 the Python executable to ensure they are available on the path. With the
467 Embedding Python
468 ----------------
471 language, and the embedded Python distribution can be used for this purpose. In
473 either invoke ``python.exe`` or directly use ``python3.dll``. For either case,
475 installation is sufficient to provide a loadable Python interpreter.
491 Installer with multi-platform compatibility, documentation, PyWin32
498 A "comprehensive Python analysis environment" with editors and other
502 Windows-specific distribution with prebuilt scientific packages and
505 Note that these packages may not include the latest versions of Python or
506 other libraries, and are not maintained or supported by the core Python team.
510 Configuring Python
513 To run Python conveniently from a command prompt, you might consider changing
516 reliable for a single, system-wide installation. If you regularly use multiple
517 versions of Python, consider using the :ref:`launcher`.
520 .. _setting-envvars:
523 ---------------------------------------
531 .. code-block:: doscon
533 C:\>set PATH=C:\Program Files\Python 3.9;%PATH%
535 C:\>python
543 :program:`python.exe` to the start is a common way to ensure the correct version
544 of Python is launched.
550 System variables, you need non-restricted access to your machine
558 The :envvar:`PYTHONPATH` variable is used by all versions of Python 2 and
559 Python 3, so you should not permanently configure this variable unless it
560 only includes code that is compatible with all of your installed Python
565 https://www.microsoft.com/en-us/wdsi/help/folder-variables
568 https://technet.microsoft.com/en-us/library/cc754250.aspx
571 https://technet.microsoft.com/en-us/library/cc755104.aspx
574 … https://support.microsoft.com/en-us/help/310519/how-to-manage-environment-variables-in-windows-xp
580 .. _windows-path-mod:
582 Finding the Python executable
583 -----------------------------
587 Besides using the automatically created start menu entry for the Python
588 interpreter, you might want to start Python in the command prompt. The
591 On the first page of the installer, an option labelled "Add Python to PATH"
594 This allows you to type :command:`python` to run the interpreter, and
596 scripts with command line options, see :ref:`using-on-cmdline` documentation.
598 If you don't enable this option at install time, you can always re-run the
600 modify the :envvar:`PATH` using the directions in :ref:`setting-envvars`. You
602 of your Python installation, delimited by a semicolon from other entries. An
606 C:\WINDOWS\system32;C:\WINDOWS;C:\Program Files\Python 3.9
608 .. _win-utf8-mode:
610 UTF-8 mode
616 Page). Python uses it for the default encoding of text files (e.g.
619 This may cause issues because UTF-8 is widely used on the internet
622 You can use UTF-8 mode to change the default text encoding to UTF-8.
623 You can enable UTF-8 mode via the ``-X utf8`` command line option, or
625 enabling UTF-8 mode, and :ref:`setting-envvars` for how to modify
628 When UTF-8 mode is enabled:
630 * :func:`locale.getpreferredencoding` returns ``'UTF-8'`` instead of
635 all use UTF-8 as their text encoding.
639 will affect all Python 3.7+ applications on your system.
640 If you have any Python 3.7+ applications which rely on the legacy
642 temporarily or use the ``-X utf8`` command line option.
645 Even when UTF-8 mode is disabled, Python uses UTF-8 by default
654 Python Launcher for Windows
659 The Python launcher for Windows is a utility which aids in locating and
660 executing of different Python versions. It allows scripts (or the
661 command-line) to indicate a preference for a specific Python version, and
662 will locate and execute that version.
665 appropriate version of Python. It will prefer per-user installations over
666 system-wide ones, and orders by language version rather than using the most
667 recently installed version.
672 ---------------
674 From the command-line
679 System-wide installations of Python 3.3 and later will put the launcher on your
681 Python, so it does not matter which version is installed. To check that the
688 You should find that the latest version of Python you have installed is
689 started - it can be exited as normal, and any additional command-line
690 arguments specified will be sent directly to Python.
692 If you have multiple versions of Python installed (e.g., 2.7 and |version|) you
693 will have noticed that Python |version| was started - to launch Python 2.7, try
698 py -2.7
700 If you want the latest version of Python 2.x you have installed, try the
705 py -2
707 You should find the latest version of Python 2.x starts.
716 Per-user installations of Python do not add the launcher to :envvar:`PATH`
724 If the launcher is run with no explicit Python version specification, and a
729 the global Python version.
734 Let's create a test Python script - create a file called ``hello.py`` with the
737 .. code-block:: python
739 #! python
741 sys.stdout.write("hello from Python %s\n" % (sys.version,))
749 You should notice the version number of your latest Python 2.x installation
752 .. code-block:: python
756 Re-executing the command should now print the latest Python 3.x information.
757 As with the above command-line examples, you can specify a more explicit
758 version qualifier. Assuming you have Python 2.6 installed, try changing the
759 first line to ``#! python2.6`` and you should find the 2.6 version
762 Note that unlike interactive use, a bare "python" will use the latest
763 version of Python 2.x that you have installed. This is for backward
764 compatibility and for compatibility with Unix, where the command ``python``
765 typically refers to Python 2.
770 The launcher should have been associated with Python files (i.e. ``.py``,
772 when you double-click on one of these files from Windows explorer the launcher
774 have the script specify the version which should be used.
776 The key benefit of this is that a single launcher can support multiple Python
780 -------------
786 be used with Python scripts on Windows and the examples above demonstrate their
789 To allow shebang lines in Python scripts to be portable between Unix and
793 * ``/usr/bin/env python``
794 * ``/usr/bin/python``
795 * ``/usr/local/bin/python``
796 * ``python``
800 .. code-block:: sh
802 #! /usr/bin/python
804 The default Python will be located and used. As many Python scripts written
810 Any of the above virtual commands can be suffixed with an explicit version
811 (either just the major version, or the major and minor version).
812 Furthermore the 32-bit version can be requested by adding "-32" after the
813 minor version. I.e. ``/usr/bin/python2.7-32`` will request usage of the
814 32-bit python 2.7.
818 Beginning with python launcher 3.7 it is possible to request 64-bit version
819 by the "-64" suffix. Furthermore it is possible to specify a major and
820 architecture without minor (i.e. ``/usr/bin/python3-64``).
823 Before looking for installed Python interpreters, this form will search the
824 executable :envvar:`PATH` for a Python executable. This corresponds to the
828 --------------------------
831 Python interpreter. For example, if you have a shebang line:
833 .. code-block:: sh
835 #! /usr/bin/python -v
837 Then Python will be started with the ``-v`` option
840 -------------
845 Two .ini files will be searched by the launcher - ``py.ini`` in the current
849 'console' version of the launcher (i.e. py.exe) and for the 'windows' version
856 Customizing default Python versions
859 In some cases, a version qualifier can be included in a command to dictate
860 which version of Python will be used by the command. A version qualifier
861 starts with a major version number and can optionally be followed by a period
862 ('.') and a minor version specifier. Furthermore it is possible to specify
863 if a 32 or 64 bit implementation shall be requested by adding "-32" or "-64".
865 For example, a shebang line of ``#!python`` has no version qualifier, while
866 ``#!python3`` has a version qualifier which specifies only a major version.
868 If no version qualifiers are found in a command, the environment
869 variable :envvar:`PY_PYTHON` can be set to specify the default version
872 "3.7", "3.7-32" or "3.7-64". (Note that the "-64" option is only
873 available with the launcher included with Python 3.7 or newer.)
875 If no minor version qualifiers are found, the environment variable
876 ``PY_PYTHON{major}`` (where ``{major}`` is the current major version qualifier
877 as determined above) can be set to specify the full version. If no such option
878 is found, the launcher will enumerate the installed Python versions and use
879 the latest minor release found for the major version, which is likely,
880 although not guaranteed, to be the most recently installed version in that
883 On 64-bit Windows with both 32-bit and 64-bit implementations of the same
884 (major.minor) Python version installed, the 64-bit version will always be
885 preferred. This will be true for both 32-bit and 64-bit implementations of the
886 launcher - a 32-bit launcher will prefer to execute a 64-bit Python installation
887 of the specified version if available. This is so the behavior of the launcher
890 whether a 32 or 64-bit version of Python and corresponding launcher was
891 installed last). As noted above, an optional "-32" or "-64" suffix can be
892 used on a version specifier to change this behaviour.
896 * If no relevant options are set, the commands ``python`` and
897 ``python2`` will use the latest Python 2.x version installed and
898 the command ``python3`` will use the latest Python 3.x installed.
903 * If ``PY_PYTHON=3``, the commands ``python`` and ``python3`` will both use
904 the latest installed Python 3 version.
906 * If ``PY_PYTHON=3.1-32``, the command ``python`` will use the 32-bit
908 installed Python (PY_PYTHON was not considered at all as a major
909 version was specified.)
912 ``python`` and ``python3`` will both use specifically 3.1
925 .. code-block:: ini
928 python=3.1
933 .. code-block:: ini
936 python=3
940 -----------
945 should allow you to see what versions of Python were located, why a
946 particular version was chosen and the exact command-line used to execute the
947 target Python.
956 Python usually stores its library (and thereby your site-packages folder) in the
957 installation directory. So, if you had installed Python to
958 :file:`C:\\Python\\`, the default library would reside in
959 :file:`C:\\Python\\Lib\\` and third-party modules should be stored in
960 :file:`C:\\Python\\Lib\\site-packages\\`.
963 name as the DLL (``python37._pth``) or the executable (``python._pth``) and
985 :ref:`using-on-envvars`, its entries are added next. Note that on Windows,
990 :samp:`\\SOFTWARE\\Python\\PythonCore\\{version}\\PythonPath` under both the
992 semicolon-delimited path strings as their default value will cause each path
997 "Python Home". Otherwise, the path of the main Python executable is used to
999 the "Python Home". If a Python home is found, the relevant sub-directories
1000 added to :data:`sys.path` (``Lib``, ``plat-win``, etc) are based on that
1001 folder. Otherwise, the core Python path is constructed from the PythonPath
1004 * If the Python Home cannot be located, no :envvar:`PYTHONPATH` is specified in
1006 relative entries is used (e.g. ``.\Lib;.\plat-win``, etc).
1017 * When running :file:`python.exe`, or any other .exe in the main Python
1018 directory (either an installed version, or directly from the PCbuild
1022 * When Python is hosted in another .exe (different directory, embedded via COM,
1023 etc), the "Python Home" will not be deduced, so the core path from the
1026 * If Python can't find its home and there are no registry value (frozen .exe,
1030 For those who want to bundle Python into their application or distribution, the
1043 before launching :file:`python.exe` from your application.
1046 distribution that allows people to run :file:`python.exe` directly), ensure
1051 These will ensure that the files in a system-wide installation will not take
1055 non-standard paths in the registry and user site-packages.
1076 Even though Python aims to be portable among all platforms, there are features
1080 The Windows-specific standard modules are documented in
1081 :ref:`mswin-specific-services`.
1084 -------
1087 is a collection of modules for advanced Windows-specific support. This includes
1091 <https://docs.microsoft.com/en-us/windows/desktop/com/component-object-model--com--portal>`_
1096 * `Microsoft Foundation Classes <https://msdn.microsoft.com/en-us/library/fe1cf721%28VS.80%29.aspx>…
1100 https://www.python.org/windows/pythonwin/>`_ is a sample MFC application
1101 shipped with PyWin32. It is an embeddable IDE with a built-in debugger.
1105 `Win32 How Do I...? <http://timgolden.me.uk/python/win32_how_do_i.html>`_
1108 `Python and COM <http://www.boddie.org.uk/python/COM.html>`_
1113 ---------
1115 `cx_Freeze <https://anthony-tuininga.github.io/cx_Freeze/>`_ is a :mod:`distutils`
1116 extension (see :ref:`extending-distutils`) which wraps Python scripts into
1119 Python.
1123 ------
1125 Since Python's advanced terminal handling layer, :mod:`curses`, is restricted to
1126 Unix-like systems, there is a library exclusive to Windows as well: Windows
1127 Console I/O for Python.
1130 Turbo-C's :file:`CONIO.H`, used to create text user interfaces.
1134 Compiling Python on Windows
1138 `source <https://www.python.org/downloads/source/>`_. You can download either the
1140 <https://devguide.python.org/setup/#getting-the-source-code>`_.
1143 Visual Studio 2015, which is the compiler used to build the official Python
1149 For extension modules, consult :ref:`building-on-windows`.
1153 `Python + Windows + distutils + SWIG + gcc MinGW <http://sebsauvage.net/python/mingw.html>`_
1154 or "Creating Python extensions in C/C++ with SWIG and compiling them with
1155 MinGW gcc under Windows" or "Installing Python extension with distutils
1162 With ongoing development of Python, some platforms that used to be supported
1167 * The `Cygwin <https://cygwin.com/>`_ installer offers to install the Python
1169 <ftp://ftp.uni-erlangen.de/pub/pc/gnuwin32/cygwin/mirrors/cygnus/
1170 release/python>`_, `Maintainer releases
1171 <http://www.tishler.net/jason/software/python/>`_)
1173 See `Python for Windows <https://www.python.org/downloads/windows/>`_
1174 for detailed information about platforms with pre-compiled installers.