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 the :ref:`Python UTF-8 Mode <utf8-mode>` to change the default text
623 encoding to UTF-8. You can enable the :ref:`Python UTF-8 Mode <utf8-mode>` via
624 the ``-X utf8`` command line option, or the ``PYTHONUTF8=1`` environment
625 variable. See :envvar:`PYTHONUTF8` for enabling UTF-8 mode, and
626 :ref:`setting-envvars` for how to modify environment variables.
628 When the :ref:`Python UTF-8 Mode <utf8-mode>` is enabled, you can still use the
632 will affect all Python 3.7+ applications on your system.
633 If you have any Python 3.7+ applications which rely on the legacy
635 temporarily or use the ``-X utf8`` command line option.
638 Even when UTF-8 mode is disabled, Python uses UTF-8 by default
648 Python Launcher for Windows
653 The Python launcher for Windows is a utility which aids in locating and
654 executing of different Python versions. It allows scripts (or the
655 command-line) to indicate a preference for a specific Python version, and
656 will locate and execute that version.
659 appropriate version of Python. It will prefer per-user installations over
660 system-wide ones, and orders by language version rather than using the most
661 recently installed version.
666 ---------------
668 From the command-line
673 System-wide installations of Python 3.3 and later will put the launcher on your
675 Python, so it does not matter which version is installed. To check that the
682 You should find that the latest version of Python you have installed is
683 started - it can be exited as normal, and any additional command-line
684 arguments specified will be sent directly to Python.
686 If you have multiple versions of Python installed (e.g., 2.7 and |version|) you
687 will have noticed that Python |version| was started - to launch Python 2.7, try
692 py -2.7
694 If you want the latest version of Python 2.x you have installed, try the
699 py -2
701 You should find the latest version of Python 2.x starts.
710 Per-user installations of Python do not add the launcher to :envvar:`PATH`
718 If the launcher is run with no explicit Python version specification, and a
723 the global Python version.
728 Let's create a test Python script - create a file called ``hello.py`` with the
731 .. code-block:: python
733 #! python
735 sys.stdout.write("hello from Python %s\n" % (sys.version,))
743 You should notice the version number of your latest Python 2.x installation
746 .. code-block:: python
750 Re-executing the command should now print the latest Python 3.x information.
751 As with the above command-line examples, you can specify a more explicit
752 version qualifier. Assuming you have Python 2.6 installed, try changing the
753 first line to ``#! python2.6`` and you should find the 2.6 version
756 Note that unlike interactive use, a bare "python" will use the latest
757 version of Python 2.x that you have installed. This is for backward
758 compatibility and for compatibility with Unix, where the command ``python``
759 typically refers to Python 2.
764 The launcher should have been associated with Python files (i.e. ``.py``,
766 when you double-click on one of these files from Windows explorer the launcher
768 have the script specify the version which should be used.
770 The key benefit of this is that a single launcher can support multiple Python
774 -------------
780 be used with Python scripts on Windows and the examples above demonstrate their
783 To allow shebang lines in Python scripts to be portable between Unix and
787 * ``/usr/bin/env python``
788 * ``/usr/bin/python``
789 * ``/usr/local/bin/python``
790 * ``python``
794 .. code-block:: sh
796 #! /usr/bin/python
798 The default Python will be located and used. As many Python scripts written
804 Any of the above virtual commands can be suffixed with an explicit version
805 (either just the major version, or the major and minor version).
806 Furthermore the 32-bit version can be requested by adding "-32" after the
807 minor version. I.e. ``/usr/bin/python2.7-32`` will request usage of the
808 32-bit python 2.7.
812 Beginning with python launcher 3.7 it is possible to request 64-bit version
813 by the "-64" suffix. Furthermore it is possible to specify a major and
814 architecture without minor (i.e. ``/usr/bin/python3-64``).
817 Before looking for installed Python interpreters, this form will search the
818 executable :envvar:`PATH` for a Python executable. This corresponds to the
822 --------------------------
825 Python interpreter. For example, if you have a shebang line:
827 .. code-block:: sh
829 #! /usr/bin/python -v
831 Then Python will be started with the ``-v`` option
834 -------------
839 Two .ini files will be searched by the launcher - ``py.ini`` in the current
843 'console' version of the launcher (i.e. py.exe) and for the 'windows' version
850 Customizing default Python versions
853 In some cases, a version qualifier can be included in a command to dictate
854 which version of Python will be used by the command. A version qualifier
855 starts with a major version number and can optionally be followed by a period
856 ('.') and a minor version specifier. Furthermore it is possible to specify
857 if a 32 or 64 bit implementation shall be requested by adding "-32" or "-64".
859 For example, a shebang line of ``#!python`` has no version qualifier, while
860 ``#!python3`` has a version qualifier which specifies only a major version.
862 If no version qualifiers are found in a command, the environment
863 variable :envvar:`PY_PYTHON` can be set to specify the default version
866 "3.7", "3.7-32" or "3.7-64". (Note that the "-64" option is only
867 available with the launcher included with Python 3.7 or newer.)
869 If no minor version qualifiers are found, the environment variable
870 ``PY_PYTHON{major}`` (where ``{major}`` is the current major version qualifier
871 as determined above) can be set to specify the full version. If no such option
872 is found, the launcher will enumerate the installed Python versions and use
873 the latest minor release found for the major version, which is likely,
874 although not guaranteed, to be the most recently installed version in that
877 On 64-bit Windows with both 32-bit and 64-bit implementations of the same
878 (major.minor) Python version installed, the 64-bit version will always be
879 preferred. This will be true for both 32-bit and 64-bit implementations of the
880 launcher - a 32-bit launcher will prefer to execute a 64-bit Python installation
881 of the specified version if available. This is so the behavior of the launcher
884 whether a 32 or 64-bit version of Python and corresponding launcher was
885 installed last). As noted above, an optional "-32" or "-64" suffix can be
886 used on a version specifier to change this behaviour.
890 * If no relevant options are set, the commands ``python`` and
891 ``python2`` will use the latest Python 2.x version installed and
892 the command ``python3`` will use the latest Python 3.x installed.
897 * If ``PY_PYTHON=3``, the commands ``python`` and ``python3`` will both use
898 the latest installed Python 3 version.
900 * If ``PY_PYTHON=3.1-32``, the command ``python`` will use the 32-bit
902 installed Python (PY_PYTHON was not considered at all as a major
903 version was specified.)
906 ``python`` and ``python3`` will both use specifically 3.1
919 .. code-block:: ini
922 python=3.1
927 .. code-block:: ini
930 python=3
934 -----------
939 should allow you to see what versions of Python were located, why a
940 particular version was chosen and the exact command-line used to execute the
941 target Python.
950 Python usually stores its library (and thereby your site-packages folder) in the
951 installation directory. So, if you had installed Python to
952 :file:`C:\\Python\\`, the default library would reside in
953 :file:`C:\\Python\\Lib\\` and third-party modules should be stored in
954 :file:`C:\\Python\\Lib\\site-packages\\`.
957 name as the DLL (``python37._pth``) or the executable (``python._pth``) and
979 :ref:`using-on-envvars`, its entries are added next. Note that on Windows,
984 :samp:`\\SOFTWARE\\Python\\PythonCore\\{version}\\PythonPath` under both the
986 semicolon-delimited path strings as their default value will cause each path
991 "Python Home". Otherwise, the path of the main Python executable is used to
993 the "Python Home". If a Python home is found, the relevant sub-directories
994 added to :data:`sys.path` (``Lib``, ``plat-win``, etc) are based on that
995 folder. Otherwise, the core Python path is constructed from the PythonPath
998 * If the Python Home cannot be located, no :envvar:`PYTHONPATH` is specified in
1000 relative entries is used (e.g. ``.\Lib;.\plat-win``, etc).
1011 * When running :file:`python.exe`, or any other .exe in the main Python
1012 directory (either an installed version, or directly from the PCbuild
1016 * When Python is hosted in another .exe (different directory, embedded via COM,
1017 etc), the "Python Home" will not be deduced, so the core path from the
1020 * If Python can't find its home and there are no registry value (frozen .exe,
1024 For those who want to bundle Python into their application or distribution, the
1037 before launching :file:`python.exe` from your application.
1040 distribution that allows people to run :file:`python.exe` directly), ensure
1045 These will ensure that the files in a system-wide installation will not take
1049 non-standard paths in the registry and user site-packages.
1070 Even though Python aims to be portable among all platforms, there are features
1074 The Windows-specific standard modules are documented in
1075 :ref:`mswin-specific-services`.
1078 -------
1081 is a collection of modules for advanced Windows-specific support. This includes
1085 <https://docs.microsoft.com/en-us/windows/desktop/com/component-object-model--com--portal>`_
1090 * `Microsoft Foundation Classes <https://msdn.microsoft.com/en-us/library/fe1cf721%28VS.80%29.aspx>…
1094 https://www.python.org/windows/pythonwin/>`_ is a sample MFC application
1095 shipped with PyWin32. It is an embeddable IDE with a built-in debugger.
1099 `Win32 How Do I...? <http://timgolden.me.uk/python/win32_how_do_i.html>`_
1102 `Python and COM <http://www.boddie.org.uk/python/COM.html>`_
1107 ---------
1109 `cx_Freeze <https://cx-freeze.readthedocs.io/en/latest/>`_ is a :mod:`distutils`
1110 extension (see :ref:`extending-distutils`) which wraps Python scripts into
1113 Python.
1117 ------
1119 Since Python's advanced terminal handling layer, :mod:`curses`, is restricted to
1120 Unix-like systems, there is a library exclusive to Windows as well: Windows
1121 Console I/O for Python.
1124 Turbo-C's :file:`CONIO.H`, used to create text user interfaces.
1128 Compiling Python on Windows
1132 `source <https://www.python.org/downloads/source/>`_. You can download either the
1134 <https://devguide.python.org/setup/#getting-the-source-code>`_.
1137 Visual Studio 2015, which is the compiler used to build the official Python
1143 For extension modules, consult :ref:`building-on-windows`.
1147 `Python + Windows + distutils + SWIG + gcc MinGW <http://sebsauvage.net/python/mingw.html>`_
1148 or "Creating Python extensions in C/C++ with SWIG and compiling them with
1149 MinGW gcc under Windows" or "Installing Python extension with distutils
1156 With ongoing development of Python, some platforms that used to be supported
1161 * The `Cygwin <https://cygwin.com/>`_ installer offers to install the Python
1163 <ftp://ftp.uni-erlangen.de/pub/pc/gnuwin32/cygwin/mirrors/cygnus/
1164 release/python>`_, `Maintainer releases
1165 <http://www.tishler.net/jason/software/python/>`_)
1167 See `Python for Windows <https://www.python.org/downloads/windows/>`_
1168 for detailed information about platforms with pre-compiled installers.