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 confirmation
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\\Python\\\ |
156 | | | Programs\\Python\\\ |
157 | | | PythonXY-32` or |
159 | | | Programs\\Python\\\ |
160 | | | PythonXY-64` |
161 +---------------------------+--------------------------------------+--------------------------+
164 +---------------------------+--------------------------------------+--------------------------+
167 +---------------------------+--------------------------------------+--------------------------+
170 +---------------------------+--------------------------------------+--------------------------+
174 +---------------------------+--------------------------------------+--------------------------+
178 +---------------------------+--------------------------------------+--------------------------+
181 +---------------------------+--------------------------------------+--------------------------+
182 | Include_doc | Install Python manual | 1 |
183 +---------------------------+--------------------------------------+--------------------------+
185 +---------------------------+--------------------------------------+--------------------------+
189 +---------------------------+--------------------------------------+--------------------------+
190 | Include_exe | Install :file:`python.exe` and | 1 |
193 +---------------------------+--------------------------------------+--------------------------+
195 +---------------------------+--------------------------------------+--------------------------+
199 +---------------------------+--------------------------------------+--------------------------+
203 +---------------------------+--------------------------------------+--------------------------+
205 +---------------------------+--------------------------------------+--------------------------+
207 +---------------------------+--------------------------------------+--------------------------+
209 +---------------------------+--------------------------------------+--------------------------+
211 +---------------------------+--------------------------------------+--------------------------+
213 +---------------------------+--------------------------------------+--------------------------+
216 +---------------------------+--------------------------------------+--------------------------+
218 +---------------------------+--------------------------------------+--------------------------+
221 +---------------------------+--------------------------------------+--------------------------+
223 For example, to silently install a default, system-wide Python installation,
226 python-3.9.0.exe /quiet InstallAllUsers=1 PrependPath=1 Include_test=0
228 To allow users to easily install a personal copy of Python without the test
232 python-3.9.0.exe InstallAllUsers=0 Include_launcher=0 Include_test=0
236 recommended for per-user installs when there is also a system-wide installation
245 .. code-block:: xml
255 .. _install-layout-option:
258 ------------------------------
260 As some features of Python are not included in the initial installer download,
262 need, all possible components may be downloaded on-demand to create a complete
269 required files. Remember to substitute ``python-3.9.0.exe`` for the actual
275 python-3.9.0.exe /layout [optional target directory]
280 --------------------
282 Once Python has been installed, you can add or remove features through the
283 Programs and Features tool that is part of Windows. Select the Python entry and
286 "Modify" allows you to add or remove features by modifying the checkboxes -
289 need to remove and then reinstall Python completely.
294 "Uninstall" will remove Python entirely, with the exception of the
298 .. _windows-store:
305 The Microsoft Store package is an easily installable Python interpreter that
309 search the Microsoft Store app for "Python |version|". Ensure that the app
310 you select is published by the Python Software Foundation, and install it.
313 Python will always be available for free on the Microsoft Store. If you
316 After installation, Python may be launched by finding it in Start.
318 session by typing ``python``. Further, pip and IDLE may be used by typing
321 All three commands are also available with version number suffixes, for
323 ``python.exe`` (where ``3.x`` is the specific version you want to launch,
324 such as |version|). Open "Manage App Execution Aliases" through Start to
325 select which version of Python is associated with each command. It is
327 whichever version of ``python`` is selected.
329 Virtual environments can be created with ``python -m venv`` and activated
332 If you have installed another version of Python and added it to your
333 ``PATH`` variable, it will be available as ``python.exe`` rather than the
337 The ``py.exe`` launcher will detect this Python installation, but will prefer
340 To remove Python, open Settings and use Apps and Features, or else find
341 Python in Start and right-click to select Uninstall. Uninstalling will
342 remove all packages you installed directly into this Python installation, but
346 ------------
351 Because of restrictions on Microsoft Store apps, Python scripts may not have
356 At runtime, Python will use a private copy of well-known Windows folders and the registry.
359 :file:`C:\\Users\\<user>\\AppData\\Local\\Packages\\PythonSoftwareFoundation.Python.3.8_qbz5n2kfra8…
367 .. code-block:: python
372 …'C:\\Users\\example\\AppData\\Local\\Packages\\PythonSoftwareFoundation.Python.3.8_qbz5n2kfra8p0\\…
382 Microsoft's documentation on packaged full-trust apps, currently available at
383 `docs.microsoft.com/en-us/windows/msix/desktop/desktop-to-uwp-behind-the-scenes
384 <https://docs.microsoft.com/en-us/windows/msix/desktop/desktop-to-uwp-behind-the-scenes>`_
387 .. _windows-nuget:
394 The nuget.org package is a reduced size Python environment intended for use on
395 continuous integration and build systems that do not have a system-wide
396 install of Python. While nuget is "the package manager for .NET", it also works
397 perfectly fine for packages containing build-time tools.
399 Visit `nuget.org <https://www.nuget.org/>`_ for the most up-to-date information
400 on using nuget. What follows is a summary that is sufficient for Python
405 tool, the latest version of Python for 64-bit or 32-bit machines is installed
408 nuget.exe install python -ExcludeVersion -OutputDirectory .
409 nuget.exe install pythonx86 -ExcludeVersion -OutputDirectory .
411 To select a particular version, add a ``-Version 3.x.y``. The output directory
414 and without the ``-ExcludeVersion`` option this name will include the specific
415 version installed. Inside the subdirectory is a ``tools`` directory that
416 contains the Python installation:
418 .. code-block:: doscon
420 # Without -ExcludeVersion
421 > .\python.3.5.2\tools\python.exe -V
422 Python 3.5.2
424 # With -ExcludeVersion
425 > .\python\tools\python.exe -V
426 Python 3.5.2
429 installed side-by-side and referenced using the full path. Alternatively,
434 contains a MSBuild properties file ``python.props`` that can be used in a
435 C++ project to reference the Python install. Including the settings will
439 `www.nuget.org/packages/python <https://www.nuget.org/packages/python>`_
440 for the 64-bit version and `www.nuget.org/packages/pythonx86
441 <https://www.nuget.org/packages/pythonx86>`_ for the 32-bit version.
444 .. _windows-embeddable:
451 The embedded distribution is a ZIP file containing a minimal Python environment.
453 directly accessed by end-users.
457 installed packages. The standard library is included as pre-compiled and
459 ``python.exe`` and ``pythonw.exe`` are all provided. Tcl/tk (including all
460 dependents, such as Idle), pip and the Python documentation are not included.
465 …<https://docs.microsoft.com/en-US/cpp/windows/latest-supported-vc-redist#visual-studio-2015-2017-2…
471 Third-party packages should be installed by the application installer alongside
473 Python installation is not supported with this distribution, though with some
475 general, third-party packages should be treated as part of the application
481 Python Application
482 ------------------
484 An application written in Python does not necessarily require users to be aware
486 private version of Python in an install package. Depending on how transparent it
492 no obvious indications that the program is running on Python: icons can be
493 customized, company and version information can be specified, and file
495 able to call ``Py_Main`` with a hard-coded command line.
498 directly calls the ``python.exe`` or ``pythonw.exe`` with the required
499 command-line arguments. In this case, the application will appear to be Python
501 running Python processes or file associations.
504 the Python executable to ensure they are available on the path. With the
508 Embedding Python
509 ----------------
512 language, and the embedded Python distribution can be used for this purpose. In
514 either invoke ``python.exe`` or directly use ``python3.dll``. For either case,
516 installation is sufficient to provide a loadable Python interpreter.
531 `ActivePython <https://www.activestate.com/products/python/>`_
532 Installer with multi-platform compatibility, documentation, PyWin32
539 "The Next Generation Python Environment and Package Manager".
542 …thought.com/hc/en-us/articles/360038600051-Canopy-GUI-end-of-life-transition-to-the-Enthought-Depl…
545 Windows-specific distribution with prebuilt scientific packages and
548 Note that these packages may not include the latest versions of Python or
549 other libraries, and are not maintained or supported by the core Python team.
553 Configuring Python
556 To run Python conveniently from a command prompt, you might consider changing
559 reliable for a single, system-wide installation. If you regularly use multiple
560 versions of Python, consider using the :ref:`launcher`.
563 .. _setting-envvars:
566 ---------------------------------------
574 .. code-block:: doscon
576 C:\>set PATH=C:\Program Files\Python 3.9;%PATH%
578 C:\>python
586 :program:`python.exe` to the start is a common way to ensure the correct version
587 of Python is launched.
593 System variables, you need non-restricted access to your machine
601 The :envvar:`PYTHONPATH` variable is used by all versions of Python,
603 only include code that is compatible with all of your installed Python
608 https://docs.microsoft.com/en-us/windows/win32/procthread/environment-variables
611 https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1
614 https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/setx
618 .. _windows-path-mod:
620 Finding the Python executable
621 -----------------------------
625 Besides using the automatically created start menu entry for the Python
626 interpreter, you might want to start Python in the command prompt. The
629 On the first page of the installer, an option labelled "Add Python to PATH"
632 This allows you to type :command:`python` to run the interpreter, and
634 scripts with command line options, see :ref:`using-on-cmdline` documentation.
636 If you don't enable this option at install time, you can always re-run the
638 modify the :envvar:`PATH` using the directions in :ref:`setting-envvars`. You
640 of your Python installation, delimited by a semicolon from other entries. An
644 C:\WINDOWS\system32;C:\WINDOWS;C:\Program Files\Python 3.9
646 .. _win-utf8-mode:
648 UTF-8 mode
654 Page). Python uses it for the default encoding of text files (e.g.
657 This may cause issues because UTF-8 is widely used on the internet
660 You can use the :ref:`Python UTF-8 Mode <utf8-mode>` to change the default text
661 encoding to UTF-8. You can enable the :ref:`Python UTF-8 Mode <utf8-mode>` via
662 the ``-X utf8`` command line option, or the ``PYTHONUTF8=1`` environment
663 variable. See :envvar:`PYTHONUTF8` for enabling UTF-8 mode, and
664 :ref:`setting-envvars` for how to modify environment variables.
666 When the :ref:`Python UTF-8 Mode <utf8-mode>` is enabled, you can still use the
670 will affect all Python 3.7+ applications on your system.
671 If you have any Python 3.7+ applications which rely on the legacy
673 temporarily or use the ``-X utf8`` command line option.
676 Even when UTF-8 mode is disabled, Python uses UTF-8 by default
686 Python Launcher for Windows
691 The Python launcher for Windows is a utility which aids in locating and
692 executing of different Python versions. It allows scripts (or the
693 command-line) to indicate a preference for a specific Python version, and
694 will locate and execute that version.
697 appropriate version of Python. It will prefer per-user installations over
698 system-wide ones, and orders by language version rather than using the most
699 recently installed version.
704 ---------------
706 From the command-line
711 System-wide installations of Python 3.3 and later will put the launcher on your
713 Python, so it does not matter which version is installed. To check that the
718 You should find that the latest version of Python you have installed is
719 started - it can be exited as normal, and any additional command-line
720 arguments specified will be sent directly to Python.
722 If you have multiple versions of Python installed (e.g., 3.7 and |version|) you
723 will have noticed that Python |version| was started - to launch Python 3.7, try
726 py -3.7
728 If you want the latest version of Python 2 you have installed, try the
731 py -2
740 py --list
742 displays the currently installed version(s) of Python.
744 The ``-x.y`` argument is the short form of the ``-V:Company/Tag`` argument,
745 which allows selecting a specific Python runtime, including those that may have
746 come from somewhere other than python.org. Any runtime registered by following
747 :pep:`514` will be discoverable. The ``--list`` command lists all available
748 runtimes using the ``-V:`` format.
750 When using the ``-V:`` argument, specifying the Company will limit selection to
755 py -V:3
758 py -V:PythonCore/
760 # Select PythonCore's latest Python 3 runtime
761 py -V:PythonCore/3
763 The short form of the argument (``-3``) only ever selects from core Python
764 releases, and not other distributions. However, the longer form (``-V:3``) will
767 The Company is matched on the full string, case-insenitive. The Tag is matched
769 hyphen. This allows ``-V:3.1`` to match ``3.1-32``, but not ``3.10``. Tags are
771 compared using text (``-V:3.01`` does not match ``3.1``).
779 If the launcher is run with no explicit Python version specification, and a
784 the global Python version.
789 Let's create a test Python script - create a file called ``hello.py`` with the
792 .. code-block:: python
794 #! python
796 sys.stdout.write("hello from Python %s\n" % (sys.version,))
802 You should notice the version number of your latest Python 2.x installation
805 .. code-block:: python
809 Re-executing the command should now print the latest Python 3.x information.
810 As with the above command-line examples, you can specify a more explicit
811 version qualifier. Assuming you have Python 3.7 installed, try changing
813 version information printed.
815 Note that unlike interactive use, a bare "python" will use the latest
816 version of Python 2.x that you have installed. This is for backward
817 compatibility and for compatibility with Unix, where the command ``python``
818 typically refers to Python 2.
823 The launcher should have been associated with Python files (i.e. ``.py``,
825 when you double-click on one of these files from Windows explorer the launcher
827 have the script specify the version which should be used.
829 The key benefit of this is that a single launcher can support multiple Python
833 -------------
839 be used with Python scripts on Windows and the examples above demonstrate their
842 To allow shebang lines in Python scripts to be portable between Unix and
847 * ``/usr/bin/python``
848 * ``/usr/local/bin/python``
849 * ``python``
853 .. code-block:: sh
855 #! /usr/bin/python
857 The default Python will be located and used. As many Python scripts written
863 Any of the above virtual commands can be suffixed with an explicit version
864 (either just the major version, or the major and minor version).
865 Furthermore the 32-bit version can be requested by adding "-32" after the
866 minor version. I.e. ``/usr/bin/python3.7-32`` will request usage of the
867 32-bit python 3.7.
871 Beginning with python launcher 3.7 it is possible to request 64-bit version
872 by the "-64" suffix. Furthermore it is possible to specify a major and
873 architecture without minor (i.e. ``/usr/bin/python3-64``).
877 The "-64" suffix is deprecated, and now implies "any architecture that is
878 not provably i386/32-bit". To request a specific environment, use the new
879 ``-V:<TAG>`` argument with the complete tag.
882 Before looking for installed Python interpreters, this form will search the
883 executable :envvar:`PATH` for a Python executable matching the name provided
887 be found, but the argument starts with ``python``, it will be handled as
893 ``[commands]`` section of the launcher's :ref:`.INI file <launcher-ini>`.
900 .. code-block:: ini
903 /bin/xpython=C:\Program Files\XPython\python.exe
907 This is a convenience for Windows-only scripts, such as those generated by an
908 installer, since the behavior is not compatible with Unix-style shells.
914 --------------------------
917 Python interpreter. For example, if you have a shebang line:
919 .. code-block:: sh
921 #! /usr/bin/python -v
923 Then Python will be started with the ``-v`` option
926 -------------
928 .. _launcher-ini:
933 Two .ini files will be searched by the launcher - ``py.ini`` in the current
936 used for both the 'console' version of the launcher (i.e. py.exe) and for the
937 'windows' version (i.e. pyw.exe).
943 Customizing default Python versions
946 In some cases, a version qualifier can be included in a command to dictate
947 which version of Python will be used by the command. A version qualifier
948 starts with a major version number and can optionally be followed by a period
949 ('.') and a minor version specifier. Furthermore it is possible to specify
950 if a 32 or 64 bit implementation shall be requested by adding "-32" or "-64".
952 For example, a shebang line of ``#!python`` has no version qualifier, while
953 ``#!python3`` has a version qualifier which specifies only a major version.
955 If no version qualifiers are found in a command, the environment
956 variable :envvar:`PY_PYTHON` can be set to specify the default version
959 "3.7", "3.7-32" or "3.7-64". (Note that the "-64" option is only
960 available with the launcher included with Python 3.7 or newer.)
962 If no minor version qualifiers are found, the environment variable
963 ``PY_PYTHON{major}`` (where ``{major}`` is the current major version qualifier
964 as determined above) can be set to specify the full version. If no such option
965 is found, the launcher will enumerate the installed Python versions and use
966 the latest minor release found for the major version, which is likely,
967 although not guaranteed, to be the most recently installed version in that
970 On 64-bit Windows with both 32-bit and 64-bit implementations of the same
971 (major.minor) Python version installed, the 64-bit version will always be
972 preferred. This will be true for both 32-bit and 64-bit implementations of the
973 launcher - a 32-bit launcher will prefer to execute a 64-bit Python installation
974 of the specified version if available. This is so the behavior of the launcher
977 whether a 32 or 64-bit version of Python and corresponding launcher was
978 installed last). As noted above, an optional "-32" or "-64" suffix can be
979 used on a version specifier to change this behaviour.
983 * If no relevant options are set, the commands ``python`` and
984 ``python2`` will use the latest Python 2.x version installed and
985 the command ``python3`` will use the latest Python 3.x installed.
990 * If ``PY_PYTHON=3``, the commands ``python`` and ``python3`` will both use
991 the latest installed Python 3 version.
993 * If ``PY_PYTHON=3.7-32``, the command ``python`` will use the 32-bit
995 installed Python (PY_PYTHON was not considered at all as a major
996 version was specified.)
999 ``python`` and ``python3`` will both use specifically 3.7
1012 .. code-block:: ini
1015 python=3.7
1020 .. code-block:: ini
1023 python=3
1027 -----------
1032 should allow you to see what versions of Python were located, why a
1033 particular version was chosen and the exact command-line used to execute the
1034 target Python. It is primarily intended for testing and debugging.
1037 -------
1041 launch Python. This may be useful for tools that want to use the launcher to
1042 detect and then launch Python directly. Note that the command written to
1043 standard output is always encoded using UTF-8, and may not render correctly in
1047 -----------------
1050 value), and the requested Python version is not installed but is available on
1055 to always try to install Python, even if it is detected. This is mainly intended
1059 ------------
1061 The following exit codes may be returned by the Python launcher. Unfortunately,
1062 there is no way to distinguish these from the exit code of Python itself.
1068 +-------------------+-------+-----------------------------------------------+
1072 +-------------------+-------+-----------------------------------------------+
1073 | RC_CREATE_PROCESS | 101 | Failed to launch Python. |
1074 +-------------------+-------+-----------------------------------------------+
1076 | | | need to be re-run after it completes. |
1077 +-------------------+-------+-----------------------------------------------+
1079 +-------------------+-------+-----------------------------------------------+
1082 +-------------------+-------+-----------------------------------------------+
1083 | RC_NO_PYTHON | 103 | Unable to locate the requested version. |
1084 +-------------------+-------+-----------------------------------------------+
1087 +-------------------+-------+-----------------------------------------------+
1095 These notes supplement the description at :ref:`sys-path-init` with
1105 :ref:`using-on-envvars`, its entries are added next. Note that on Windows,
1110 :samp:`\\SOFTWARE\\Python\\PythonCore\\{version}\\PythonPath` under both the
1112 semicolon-delimited path strings as their default value will cause each path
1117 "Python Home". Otherwise, the path of the main Python executable is used to
1119 the "Python Home". If a Python home is found, the relevant sub-directories
1120 added to :data:`sys.path` (``Lib``, ``plat-win``, etc) are based on that
1121 folder. Otherwise, the core Python path is constructed from the PythonPath
1124 * If the Python Home cannot be located, no :envvar:`PYTHONPATH` is specified in
1126 relative entries is used (e.g. ``.\Lib;.\plat-win``, etc).
1137 * When running :file:`python.exe`, or any other .exe in the main Python
1138 directory (either an installed version, or directly from the PCbuild
1142 * When Python is hosted in another .exe (different directory, embedded via COM,
1143 etc), the "Python Home" will not be deduced, so the core path from the
1146 * If Python can't find its home and there are no registry value (frozen .exe,
1150 For those who want to bundle Python into their application or distribution, the
1163 before launching :file:`python.exe` from your application.
1166 distribution that allows people to run :file:`python.exe` directly), ensure
1171 These will ensure that the files in a system-wide installation will not take
1175 non-standard paths in the registry and user site-packages.
1196 Even though Python aims to be portable among all platforms, there are features
1200 The Windows-specific standard modules are documented in
1201 :ref:`mswin-specific-services`.
1204 -------
1207 is a collection of modules for advanced Windows-specific support. This includes
1211 <https://docs.microsoft.com/en-us/windows/win32/com/component-object-model--com--portal>`_
1217 <https://docs.microsoft.com/en-us/cpp/mfc/mfc-desktop-applications>`_
1221 https://www.python.org/windows/pythonwin/>`_ is a sample MFC application
1222 shipped with PyWin32. It is an embeddable IDE with a built-in debugger.
1226 `Win32 How Do I...? <http://timgolden.me.uk/python/win32_how_do_i.html>`_
1229 `Python and COM <https://www.boddie.org.uk/python/COM.html>`_
1234 ---------
1236 `cx_Freeze <https://cx-freeze.readthedocs.io/en/latest/>`_ is a :mod:`distutils`
1237 extension (see :ref:`extending-distutils`) which wraps Python scripts into
1240 Python.
1243 Compiling Python on Windows
1247 `source <https://www.python.org/downloads/source/>`_. You can download either the
1249 <https://devguide.python.org/setup/#get-the-source-code>`_.
1252 Visual Studio, which is the compiler used to build the official Python
1257 For extension modules, consult :ref:`building-on-windows`.
1263 With ongoing development of Python, some platforms that used to be supported
1268 `no longer supported <https://github.com/python/cpython/issues/71542>`__
1269 since Python 3 (if it ever was).
1271 `Python interpreter <https://cygwin.com/packages/summary/python3.html>`__
1274 See `Python for Windows <https://www.python.org/downloads/windows/>`_
1275 for detailed information about platforms with pre-compiled installers.