2488 lines
191 KiB
HTML
2488 lines
191 KiB
HTML
<!DOCTYPE html>
|
||
|
||
<html lang="en" data-content_root="../">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||
<meta property="og:title" content="4. Using Python on Windows" />
|
||
<meta property="og:type" content="website" />
|
||
<meta property="og:url" content="https://docs.python.org/3/using/windows.html" />
|
||
<meta property="og:site_name" content="Python documentation" />
|
||
<meta property="og:description" content="This document aims to give an overview of Windows-specific behaviour you should know about when using Python on Microsoft Windows. Unlike most Unix systems and services, Windows does not include a ..." />
|
||
<meta property="og:image" content="_static/og-image.png" />
|
||
<meta property="og:image:alt" content="Python documentation" />
|
||
<meta name="description" content="This document aims to give an overview of Windows-specific behaviour you should know about when using Python on Microsoft Windows. Unlike most Unix systems and services, Windows does not include a ..." />
|
||
<meta name="theme-color" content="#3776ab">
|
||
<meta property="og:image:width" content="200">
|
||
<meta property="og:image:height" content="200">
|
||
|
||
<title>4. Using Python on Windows — Python 3.15.0 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
|
||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
|
||
<link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />
|
||
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=48df1187" />
|
||
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=0fc419ee" />
|
||
|
||
<script src="../_static/documentation_options.js?v=0fe728b1"></script>
|
||
<script src="../_static/doctools.js?v=9bcbadda"></script>
|
||
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
|
||
|
||
<script src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="Search within Python 3.15.0 documentation"
|
||
href="../_static/opensearch.xml"/>
|
||
<link rel="author" title="About these documents" href="../about.html" />
|
||
<link rel="index" title="Index" href="../genindex.html" />
|
||
<link rel="search" title="Search" href="../search.html" />
|
||
<link rel="copyright" title="Copyright" href="../copyright.html" />
|
||
<link rel="next" title="5. Using Python on macOS" href="mac.html" />
|
||
<link rel="prev" title="3. Configure Python" href="configure.html" />
|
||
|
||
|
||
<link rel="canonical" href="https://docs.python.org/3/using/windows.html">
|
||
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.svg">
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/menu.js"></script>
|
||
<script type="text/javascript" src="../_static/search-focus.js"></script>
|
||
<script type="text/javascript" src="../_static/themetoggle.js"></script>
|
||
<script type="text/javascript" src="../_static/rtd_switcher.js"></script>
|
||
<meta name="readthedocs-addons-api-version" content="1">
|
||
|
||
</head>
|
||
<body>
|
||
<div class="mobile-nav">
|
||
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
|
||
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">
|
||
<nav class="nav-content" role="navigation">
|
||
<label for="menuToggler" class="toggler__label">
|
||
<span></span>
|
||
</label>
|
||
<span class="nav-items-wrapper">
|
||
<a href="https://www.python.org/" class="nav-logo">
|
||
<img src="../_static/py.svg" alt="Python logo">
|
||
</a>
|
||
<span class="version_switcher_placeholder"></span>
|
||
<form role="search" class="search" action="../search.html" method="get">
|
||
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
|
||
<path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>
|
||
</svg>
|
||
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q">
|
||
<input type="submit" value="Go">
|
||
</form>
|
||
</span>
|
||
</nav>
|
||
<div class="menu-wrapper">
|
||
<nav class="menu" role="navigation" aria-label="main navigation">
|
||
<div class="language_switcher_placeholder"></div>
|
||
|
||
<label class="theme-selector-label">
|
||
Theme
|
||
<select class="theme-selector" oninput="activateTheme(this.value)">
|
||
<option value="auto" selected>Auto</option>
|
||
<option value="light">Light</option>
|
||
<option value="dark">Dark</option>
|
||
</select>
|
||
</label>
|
||
<div>
|
||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#">4. Using Python on Windows</a><ul>
|
||
<li><a class="reference internal" href="#python-install-manager">4.1. Python install manager</a><ul>
|
||
<li><a class="reference internal" href="#installation">4.1.1. Installation</a></li>
|
||
<li><a class="reference internal" href="#basic-use">4.1.2. Basic use</a></li>
|
||
<li><a class="reference internal" href="#command-help">4.1.3. Command help</a></li>
|
||
<li><a class="reference internal" href="#listing-runtimes">4.1.4. Listing runtimes</a></li>
|
||
<li><a class="reference internal" href="#installing-runtimes">4.1.5. Installing runtimes</a></li>
|
||
<li><a class="reference internal" href="#offline-installs">4.1.6. Offline installs</a></li>
|
||
<li><a class="reference internal" href="#uninstalling-runtimes">4.1.7. Uninstalling runtimes</a></li>
|
||
<li><a class="reference internal" href="#configuration">4.1.8. Configuration</a></li>
|
||
<li><a class="reference internal" href="#shebang-lines">4.1.9. Shebang lines</a></li>
|
||
<li><a class="reference internal" href="#advanced-installation">4.1.10. Advanced installation</a></li>
|
||
<li><a class="reference internal" href="#administrative-configuration">4.1.11. Administrative configuration</a></li>
|
||
<li><a class="reference internal" href="#installing-free-threaded-binaries">4.1.12. Installing free-threaded binaries</a></li>
|
||
<li><a class="reference internal" href="#index-signatures">4.1.13. Index signatures</a></li>
|
||
<li><a class="reference internal" href="#proxy-settings">4.1.14. Proxy settings</a></li>
|
||
<li><a class="reference internal" href="#troubleshooting">4.1.15. Troubleshooting</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#the-embeddable-package">4.2. The embeddable package</a><ul>
|
||
<li><a class="reference internal" href="#python-application">4.2.1. Python application</a></li>
|
||
<li><a class="reference internal" href="#embedding-python">4.2.2. Embedding Python</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#the-nuget-org-packages">4.3. The nuget.org packages</a><ul>
|
||
<li><a class="reference internal" href="#free-threaded-packages">4.3.1. Free-threaded packages</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#alternative-bundles">4.4. Alternative bundles</a></li>
|
||
<li><a class="reference internal" href="#supported-windows-versions">4.5. Supported Windows versions</a></li>
|
||
<li><a class="reference internal" href="#removing-the-max-path-limitation">4.6. Removing the MAX_PATH limitation</a></li>
|
||
<li><a class="reference internal" href="#utf-8-mode">4.7. UTF-8 mode</a></li>
|
||
<li><a class="reference internal" href="#finding-modules">4.8. Finding modules</a></li>
|
||
<li><a class="reference internal" href="#additional-modules">4.9. Additional modules</a><ul>
|
||
<li><a class="reference internal" href="#pywin32">4.9.1. PyWin32</a></li>
|
||
<li><a class="reference internal" href="#cx-freeze">4.9.2. cx_Freeze</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#compiling-python-on-windows">4.10. Compiling Python on Windows</a></li>
|
||
<li><a class="reference internal" href="#the-full-installer-deprecated">4.11. The full installer (deprecated)</a><ul>
|
||
<li><a class="reference internal" href="#installation-steps">4.11.1. Installation steps</a></li>
|
||
<li><a class="reference internal" href="#id2">4.11.2. Removing the MAX_PATH limitation</a></li>
|
||
<li><a class="reference internal" href="#installing-without-ui">4.11.3. Installing without UI</a></li>
|
||
<li><a class="reference internal" href="#installing-without-downloading">4.11.4. Installing without downloading</a></li>
|
||
<li><a class="reference internal" href="#modifying-an-install">4.11.5. Modifying an install</a></li>
|
||
<li><a class="reference internal" href="#id3">4.11.6. Installing free-threaded binaries</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#python-launcher-for-windows-deprecated">4.12. Python launcher for Windows (deprecated)</a><ul>
|
||
<li><a class="reference internal" href="#getting-started">4.12.1. Getting started</a><ul>
|
||
<li><a class="reference internal" href="#from-the-command-line">4.12.1.1. From the command-line</a></li>
|
||
<li><a class="reference internal" href="#virtual-environments">4.12.1.2. Virtual environments</a></li>
|
||
<li><a class="reference internal" href="#from-a-script">4.12.1.3. From a script</a></li>
|
||
<li><a class="reference internal" href="#from-file-associations">4.12.1.4. From file associations</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#id4">4.12.2. Shebang lines</a></li>
|
||
<li><a class="reference internal" href="#arguments-in-shebang-lines">4.12.3. Arguments in shebang lines</a></li>
|
||
<li><a class="reference internal" href="#customization">4.12.4. Customization</a><ul>
|
||
<li><a class="reference internal" href="#customization-via-ini-files">4.12.4.1. Customization via INI files</a></li>
|
||
<li><a class="reference internal" href="#customizing-default-python-versions">4.12.4.2. Customizing default Python versions</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#diagnostics">4.12.5. Diagnostics</a></li>
|
||
<li><a class="reference internal" href="#dry-run">4.12.6. Dry run</a></li>
|
||
<li><a class="reference internal" href="#install-on-demand">4.12.7. Install on demand</a></li>
|
||
<li><a class="reference internal" href="#return-codes">4.12.8. Return codes</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
<div>
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="configure.html"
|
||
title="previous chapter"><span class="section-number">3. </span>Configure Python</a></p>
|
||
</div>
|
||
<div>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="mac.html"
|
||
title="next chapter"><span class="section-number">5. </span>Using Python on macOS</a></p>
|
||
</div>
|
||
<script>
|
||
document.addEventListener('DOMContentLoaded', () => {
|
||
const title = document.querySelector('meta[property="og:title"]').content;
|
||
const elements = document.querySelectorAll('.improvepage');
|
||
const pageurl = window.location.href.split('?')[0];
|
||
elements.forEach(element => {
|
||
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
|
||
url.searchParams.set('pagetitle', title);
|
||
url.searchParams.set('pageurl', pageurl);
|
||
url.searchParams.set('pagesource', "using/windows.rst");
|
||
element.href = url.toString();
|
||
});
|
||
});
|
||
</script>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">Report a bug</a></li>
|
||
<li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.15/Doc/using/windows.rst?plain=1"
|
||
rel="nofollow">Show source
|
||
</a>
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
<div class="related" role="navigation" aria-label="Related">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="mac.html" title="5. Using Python on macOS"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="configure.html" title="3. Configure Python"
|
||
accesskey="P">previous</a> |</li>
|
||
|
||
<li class="root-icon"><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.15.0 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Python Setup and Usage</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href=""><span class="section-number">4. </span>Using Python on Windows</a></li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
|
||
<input type="submit" value="Go">
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
<li class="right">
|
||
<label class="theme-selector-label">
|
||
Theme
|
||
<select class="theme-selector" oninput="activateTheme(this.value)">
|
||
<option value="auto" selected>Auto</option>
|
||
<option value="light">Light</option>
|
||
<option value="dark">Dark</option>
|
||
</select>
|
||
</label> |</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<section id="using-python-on-windows">
|
||
<span id="using-on-windows"></span><h1><span class="section-number">4. </span>Using Python on Windows<a class="headerlink" href="#using-python-on-windows" title="Link to this heading">¶</a></h1>
|
||
<p>This document aims to give an overview of Windows-specific behaviour you should
|
||
know about when using Python on Microsoft Windows.</p>
|
||
<p>Unlike most Unix systems and services, Windows does not include a system
|
||
supported installation of Python. Instead, Python can be obtained from a number
|
||
of distributors, including directly from the CPython team. Each Python
|
||
distribution will have its own benefits and drawbacks, however, consistency with
|
||
other tools you are using is generally a worthwhile benefit. Before committing
|
||
to the process described here, we recommend investigating your existing tools to
|
||
see if they can provide Python directly.</p>
|
||
<p>To obtain Python from the CPython team, use the Python Install Manager. This
|
||
is a standalone tool that makes Python available as global commands on your
|
||
Windows machine, integrates with the system, and supports updates over time. You
|
||
can download the Python Install Manager from <a class="reference external" href="https://www.python.org/downloads/">python.org/downloads</a> or through
|
||
the <a class="reference external" href="https://apps.microsoft.com/detail/9NQ7512CXL7T">Microsoft Store app</a>.</p>
|
||
<p>Once you have installed the Python Install Manager, the global <code class="docutils literal notranslate"><span class="pre">python</span></code>
|
||
command can be used from any terminal to launch your current latest version of
|
||
Python. This version may change over time as you add or remove different
|
||
versions, and the <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">list</span></code> command will show which is current.</p>
|
||
<p>In general, we recommend that you create a <a class="reference internal" href="../tutorial/venv.html#tut-venv"><span class="std std-ref">virtual environment</span></a>
|
||
for each project and run <code class="docutils literal notranslate"><span class="pre"><env>\Scripts\Activate</span></code> in your terminal to use it.
|
||
This provides isolation between projects, consistency over time, and ensures
|
||
that additional commands added by packages are also available in your session.
|
||
Create a virtual environment using <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-m</span> <span class="pre">venv</span> <span class="pre"><env</span> <span class="pre">path></span></code>.</p>
|
||
<p>If the <code class="docutils literal notranslate"><span class="pre">python</span></code> or <code class="docutils literal notranslate"><span class="pre">py</span></code> commands do not seem to be working, please see the
|
||
<a class="reference internal" href="#pymanager-troubleshoot"><span class="std std-ref">Troubleshooting</span></a> section below. There are
|
||
sometimes additional manual steps required to configure your PC.</p>
|
||
<p>Apart from using the Python install manager, Python can also be obtained as
|
||
NuGet packages. See <a class="reference internal" href="#windows-nuget"><span class="std std-ref">The nuget.org packages</span></a> below for more information on these
|
||
packages.</p>
|
||
<p>The embeddable distros are minimal packages of Python suitable for embedding
|
||
into larger applications. They can be installed using the Python install
|
||
manager. See <a class="reference internal" href="#windows-embeddable"><span class="std std-ref">The embeddable package</span></a> below for more information on these
|
||
packages.</p>
|
||
<section id="python-install-manager">
|
||
<span id="launcher"></span><span id="windows-path-mod"></span><span id="setting-envvars"></span><span id="windows-store"></span><span id="pymanager"></span><h2><span class="section-number">4.1. </span>Python install manager<a class="headerlink" href="#python-install-manager" title="Link to this heading">¶</a></h2>
|
||
<section id="installation">
|
||
<h3><span class="section-number">4.1.1. </span>Installation<a class="headerlink" href="#installation" title="Link to this heading">¶</a></h3>
|
||
<p>The Python install manager can be installed from the <a class="reference external" href="https://apps.microsoft.com/detail/9NQ7512CXL7T">Microsoft Store app</a>
|
||
or downloaded and installed from <a class="reference external" href="https://www.python.org/downloads/">python.org/downloads</a>. The two versions are
|
||
identical.</p>
|
||
<p>To install through the Store, simply click “Install”. After it has completed,
|
||
open a terminal and type <code class="docutils literal notranslate"><span class="pre">python</span></code> to get started.</p>
|
||
<p>To install the file downloaded from python.org, either double-click and select
|
||
“Install”, or run <code class="docutils literal notranslate"><span class="pre">Add-AppxPackage</span> <span class="pre"><path</span> <span class="pre">to</span> <span class="pre">MSIX></span></code> in Windows Powershell.</p>
|
||
<p>After installation, the <code class="docutils literal notranslate"><span class="pre">python</span></code>, <code class="docutils literal notranslate"><span class="pre">py</span></code>, and <code class="docutils literal notranslate"><span class="pre">pymanager</span></code> commands should be
|
||
available. If you have existing installations of Python, or you have modified
|
||
your <span class="target" id="index-0"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code> variable, you may need to remove them or undo the
|
||
modifications. See <a class="reference internal" href="#pymanager-troubleshoot"><span class="std std-ref">Troubleshooting</span></a> for more help with fixing
|
||
non-working commands.</p>
|
||
<p>When you first install a runtime, you will likely be prompted to add a directory
|
||
to your <span class="target" id="index-1"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code>. This is optional, if you prefer to use the <code class="docutils literal notranslate"><span class="pre">py</span></code>
|
||
command, but is offered for those who prefer the full range of aliases (such
|
||
as <code class="docutils literal notranslate"><span class="pre">python3.14.exe</span></code>) to be available. The directory will be
|
||
<code class="file docutils literal notranslate"><span class="pre">%LocalAppData%\Python\bin</span></code> by default, but may be customized by an
|
||
administrator. Click Start and search for “Edit environment variables for your
|
||
account” for the system settings page to add the path.</p>
|
||
<p>Each Python runtime you install will have its own directory for scripts. These
|
||
also need to be added to <span class="target" id="index-2"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code> if you want to use them.</p>
|
||
<p>The Python install manager will be automatically updated to new releases. This
|
||
does not affect any installs of Python runtimes. Uninstalling the Python install
|
||
manager does not uninstall any Python runtimes.</p>
|
||
<p>If you are not able to install an MSIX in your context, for example, you are
|
||
using automated deployment software that does not support it, or are targeting
|
||
Windows Server 2019, please see <a class="reference internal" href="#pymanager-advancedinstall"><span class="std std-ref">Advanced installation</span></a> below for more
|
||
information.</p>
|
||
</section>
|
||
<section id="basic-use">
|
||
<h3><span class="section-number">4.1.2. </span>Basic use<a class="headerlink" href="#basic-use" title="Link to this heading">¶</a></h3>
|
||
<p>The recommended command for launching Python is <code class="docutils literal notranslate"><span class="pre">python</span></code>, which will either
|
||
launch the version requested by the script being launched, an active virtual
|
||
environment, or the default installed version, which will be the latest stable
|
||
release unless configured otherwise. If no version is specifically requested and
|
||
no runtimes are installed at all, the current latest release will be installed
|
||
automatically.</p>
|
||
<p>For all scenarios involving multiple runtime versions, the recommended command
|
||
is <code class="docutils literal notranslate"><span class="pre">py</span></code>. This may be used anywhere in place of <code class="docutils literal notranslate"><span class="pre">python</span></code> or the older
|
||
<code class="docutils literal notranslate"><span class="pre">py.exe</span></code> launcher. By default, <code class="docutils literal notranslate"><span class="pre">py</span></code> matches the behaviour of <code class="docutils literal notranslate"><span class="pre">python</span></code>, but
|
||
also allows command line options to select a specific version as well as
|
||
subcommands to manage installations. These are detailed below.</p>
|
||
<p>Because the <code class="docutils literal notranslate"><span class="pre">py</span></code> command may already be taken by the previous version, there
|
||
is also an unambiguous <code class="docutils literal notranslate"><span class="pre">pymanager</span></code> command. Scripted installs that are
|
||
intending to use Python install manager should consider using <code class="docutils literal notranslate"><span class="pre">pymanager</span></code>, due
|
||
to the lower chance of encountering a conflict with existing installs. The only
|
||
difference between the two commands is when running without any arguments:
|
||
<code class="docutils literal notranslate"><span class="pre">py</span></code> will launch your default interpreter, while <code class="docutils literal notranslate"><span class="pre">pymanager</span></code> will display
|
||
help (<code class="docutils literal notranslate"><span class="pre">pymanager</span> <span class="pre">exec</span> <span class="pre">...</span></code> provides equivalent behaviour to <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">...</span></code>).</p>
|
||
<p>Each of these commands also has a windowed version that avoids creating a
|
||
console window. These are <code class="docutils literal notranslate"><span class="pre">pyw</span></code>, <code class="docutils literal notranslate"><span class="pre">pythonw</span></code> and <code class="docutils literal notranslate"><span class="pre">pywmanager</span></code>. A <code class="docutils literal notranslate"><span class="pre">python3</span></code>
|
||
command is also included that mimics the <code class="docutils literal notranslate"><span class="pre">python</span></code> command. It is intended to
|
||
catch accidental uses of the typical POSIX command on Windows, but is not meant
|
||
to be widely used or recommended.</p>
|
||
<p>To launch your default runtime, run <code class="docutils literal notranslate"><span class="pre">python</span></code> or <code class="docutils literal notranslate"><span class="pre">py</span></code> with the arguments you
|
||
want to be passed to the runtime (such as script files or the module to launch):</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$> py
|
||
...
|
||
$> python my-script.py
|
||
...
|
||
$> py -m this
|
||
...
|
||
</pre></div>
|
||
</div>
|
||
<p>The default runtime can be overridden with the <span class="target" id="index-3"></span><a class="reference internal" href="#envvar-PYTHON_MANAGER_DEFAULT"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHON_MANAGER_DEFAULT</span></code></a>
|
||
environment variable, or a configuration file. See <a class="reference internal" href="#pymanager-config"><span class="std std-ref">Configuration</span></a> for
|
||
information about configuration settings.</p>
|
||
<p>To launch a specific runtime, the <code class="docutils literal notranslate"><span class="pre">py</span></code> command accepts a <code class="docutils literal notranslate"><span class="pre">-V:<TAG></span></code> option.
|
||
This option must be specified before any others. The tag is part or all of the
|
||
identifier for the runtime; for those from the CPython team, it looks like the
|
||
version, potentially with the platform. For compatibility, the <code class="docutils literal notranslate"><span class="pre">V:</span></code> may be
|
||
omitted in cases where the tag refers to an official release and starts with
|
||
<code class="docutils literal notranslate"><span class="pre">3</span></code>.</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$> py -V:3.14 ...
|
||
$> py -V:3-arm64 ...
|
||
</pre></div>
|
||
</div>
|
||
<p>Runtimes from other distributors may require the <em>company</em> to be included as
|
||
well.
|
||
It should be separated from the tag by a slash (either <code class="docutils literal notranslate"><span class="pre">/</span></code> or <code class="docutils literal notranslate"><span class="pre">\</span></code>),
|
||
and may be shortened to any prefix of its full value.
|
||
Specifying the company is optional when it is <code class="docutils literal notranslate"><span class="pre">PythonCore</span></code>, and specifying the
|
||
tag is optional (but not the slash) when you want the latest release from a
|
||
specific company.</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$> py -V:Distributor\1.0 ...
|
||
$> py -V:distrib/ ...
|
||
</pre></div>
|
||
</div>
|
||
<p>If no version is specified, but a script file is passed, the script will be
|
||
inspected for a <em>shebang line</em>. This is a special format for the first line in
|
||
a file that allows overriding the command. See <a class="reference internal" href="#pymanager-shebang"><span class="std std-ref">Shebang lines</span></a> for more
|
||
information. When there is no shebang line, or it cannot be resolved, the script
|
||
will be launched with the default runtime.</p>
|
||
<p>If you are running in an active virtual environment, have not requested a
|
||
particular version, and there is no shebang line, the default runtime will be
|
||
that virtual environment. In this scenario, the <code class="docutils literal notranslate"><span class="pre">python</span></code> command was likely
|
||
already overridden and none of these checks occurred. However, this behaviour
|
||
ensures that the <code class="docutils literal notranslate"><span class="pre">py</span></code> command can be used interchangeably.</p>
|
||
<p>When no runtimes are installed, any launch command will try to install the
|
||
requested version and launch it. However, after any version is installed, only
|
||
the <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">exec</span> <span class="pre">...</span></code> and <code class="docutils literal notranslate"><span class="pre">pymanager</span> <span class="pre">exec</span> <span class="pre">...</span></code> commands will install if the
|
||
requested version is absent. Other forms of commands will display an error and
|
||
direct you to use <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">install</span></code> first.</p>
|
||
</section>
|
||
<section id="command-help">
|
||
<h3><span class="section-number">4.1.3. </span>Command help<a class="headerlink" href="#command-help" title="Link to this heading">¶</a></h3>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">help</span></code> command will display the full list of supported commands, along
|
||
with their options. Any command may be passed the <code class="docutils literal notranslate"><span class="pre">-?</span></code> option to display its
|
||
help, or its name passed to <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">help</span></code>.</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$> py help
|
||
$> py help install
|
||
$> py install /?
|
||
</pre></div>
|
||
</div>
|
||
<p>All commands support some common options, which will be shown by <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">help</span></code>.
|
||
These options must be specified after any subcommand. Specifying <code class="docutils literal notranslate"><span class="pre">-v</span></code> or
|
||
<code class="docutils literal notranslate"><span class="pre">--verbose</span></code> will increase the amount of output shown, and <code class="docutils literal notranslate"><span class="pre">-vv</span></code> will
|
||
increase it further for debugging purposes. Passing <code class="docutils literal notranslate"><span class="pre">-q</span></code> or <code class="docutils literal notranslate"><span class="pre">--quiet</span></code> will
|
||
reduce output, and <code class="docutils literal notranslate"><span class="pre">-qq</span></code> will reduce it further.</p>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">--config=<PATH></span></code> option allows specifying a configuration file to
|
||
override multiple settings at once. See <a class="reference internal" href="#pymanager-config"><span class="std std-ref">Configuration</span></a> below for more
|
||
information about these files.</p>
|
||
</section>
|
||
<section id="listing-runtimes">
|
||
<h3><span class="section-number">4.1.4. </span>Listing runtimes<a class="headerlink" href="#listing-runtimes" title="Link to this heading">¶</a></h3>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$> py list [-f=|--format=<FMT>] [-1|--one] [--online|-s=|--source=<URL>] [<TAG>...]
|
||
</pre></div>
|
||
</div>
|
||
<p>The list of installed runtimes can be seen using <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">list</span></code>. A filter may be
|
||
added in the form of one or more tags (with or without company specifier), and
|
||
each may include a <code class="docutils literal notranslate"><span class="pre"><</span></code>, <code class="docutils literal notranslate"><span class="pre"><=</span></code>, <code class="docutils literal notranslate"><span class="pre">>=</span></code> or <code class="docutils literal notranslate"><span class="pre">></span></code> prefix to restrict to a range.</p>
|
||
<p>A range of formats are supported, and can be passed as the <code class="docutils literal notranslate"><span class="pre">--format=<FMT></span></code> or
|
||
<code class="docutils literal notranslate"><span class="pre">-f</span> <span class="pre"><FMT></span></code> option. Formats include <code class="docutils literal notranslate"><span class="pre">table</span></code> (a user friendly table view),
|
||
<code class="docutils literal notranslate"><span class="pre">csv</span></code> (comma-separated table), <code class="docutils literal notranslate"><span class="pre">json</span></code> (a single JSON blob), <code class="docutils literal notranslate"><span class="pre">jsonl</span></code> (one
|
||
JSON blob per result), <code class="docutils literal notranslate"><span class="pre">exe</span></code> (just the executable path), <code class="docutils literal notranslate"><span class="pre">prefix</span></code> (just the
|
||
prefix path).</p>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">--one</span></code> or <code class="docutils literal notranslate"><span class="pre">-1</span></code> option only displays a single result. If the default
|
||
runtime is included, it will be the one. Otherwise, the “best” result is shown
|
||
(“best” is deliberately vaguely defined, but will usually be the most recent
|
||
version). The result shown by <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">list</span> <span class="pre">--one</span> <span class="pre"><TAG></span></code> will match the runtime
|
||
that would be launched by <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">-V:<TAG></span></code>.</p>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">--only-managed</span></code> option excludes results that were not installed by the
|
||
Python install manager. This is useful when determining which runtimes may be
|
||
updated or uninstalled through the <code class="docutils literal notranslate"><span class="pre">py</span></code> command.</p>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">--online</span></code> option is short for passing <code class="docutils literal notranslate"><span class="pre">--source=<URL></span></code> with the default
|
||
source. Passing either of these options will search the online index for
|
||
runtimes that can be installed. The result shown by <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">list</span> <span class="pre">--online</span> <span class="pre">--one</span>
|
||
<span class="pre"><TAG></span></code> will match the runtime that would be installed by <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">install</span> <span class="pre"><TAG></span></code>.</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$> py list --online 3.14
|
||
</pre></div>
|
||
</div>
|
||
<p>For compatibility with the old launcher, the <code class="docutils literal notranslate"><span class="pre">--list</span></code>, <code class="docutils literal notranslate"><span class="pre">--list-paths</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">-0</span></code> and <code class="docutils literal notranslate"><span class="pre">-0p</span></code> commands (e.g. <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">-0p</span></code>) are retained. They do not allow
|
||
additional options, and will produce legacy formatted output.</p>
|
||
</section>
|
||
<section id="installing-runtimes">
|
||
<h3><span class="section-number">4.1.5. </span>Installing runtimes<a class="headerlink" href="#installing-runtimes" title="Link to this heading">¶</a></h3>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$> py install [-s=|--source=<URL>] [-f|--force] [-u|--update] [--dry-run] [<TAG>...]
|
||
</pre></div>
|
||
</div>
|
||
<p>New runtime versions may be added using <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">install</span></code>. One or more tags may be
|
||
specified, and the special tag <code class="docutils literal notranslate"><span class="pre">default</span></code> may be used to select the default.
|
||
Ranges are not supported for installation.</p>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">--source=<URL></span></code> option allows overriding the online index that is used to
|
||
obtain runtimes. This may be used with an offline index, as shown in
|
||
<a class="reference internal" href="#pymanager-offline"><span class="std std-ref">Offline installs</span></a>.</p>
|
||
<p>Passing <code class="docutils literal notranslate"><span class="pre">--force</span></code> will ignore any cached files and remove any existing install
|
||
to replace it with the specified one.</p>
|
||
<p>Passing <code class="docutils literal notranslate"><span class="pre">--update</span></code> will replace existing installs if the new version is newer.
|
||
Otherwise, they will be left. If no tags are provided with <code class="docutils literal notranslate"><span class="pre">--update</span></code>, all
|
||
installs managed by the Python install manager will be updated if newer versions
|
||
are available. Updates will remove any modifications made to the install,
|
||
including globally installed packages, but virtual environments will continue to
|
||
work.</p>
|
||
<p>Passing <code class="docutils literal notranslate"><span class="pre">--dry-run</span></code> will generate output and logs, but will not modify any
|
||
installs.</p>
|
||
<p>Passing <code class="docutils literal notranslate"><span class="pre">--refresh</span></code> will update all registrations for installed runtimes. This
|
||
will recreate Start menu shortcuts, registry keys, and global aliases (such as
|
||
<code class="docutils literal notranslate"><span class="pre">python3.14.exe</span></code> or for any installed scripts). These are automatically
|
||
refreshed on installation of any runtime, but may need to be manually refreshed
|
||
after installing packages.</p>
|
||
<p>In addition to the above options, the <code class="docutils literal notranslate"><span class="pre">--target</span></code> option will extract the
|
||
runtime to the specified directory instead of doing a normal install.
|
||
This is useful for embedding runtimes into larger applications.
|
||
Unlike a normal install, <code class="docutils literal notranslate"><span class="pre">py</span></code> will not be aware of the extracted runtime,
|
||
and no Start menu or other shortcuts will be created.
|
||
To launch the runtime, directly execute the main executable (typically
|
||
<code class="docutils literal notranslate"><span class="pre">python.exe</span></code>) in the target directory.</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$> py install ... [-t=|--target=<PATH>] <TAG>
|
||
</pre></div>
|
||
</div>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">exec</span></code> command will install the requested runtime if it is not already
|
||
present. This is controlled by the <code class="docutils literal notranslate"><span class="pre">automatic_install</span></code> configuration
|
||
(<span class="target" id="index-4"></span><a class="reference internal" href="#envvar-PYTHON_MANAGER_AUTOMATIC_INSTALL"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHON_MANAGER_AUTOMATIC_INSTALL</span></code></a>), and is enabled by default.
|
||
If no runtimes are available at all, all launch commands will do an automatic
|
||
install if the configuration setting allows. This is to ensure a good experience
|
||
for new users, but should not generally be relied on rather than using the
|
||
<code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">exec</span></code> command or explicit install commands.</p>
|
||
</section>
|
||
<section id="offline-installs">
|
||
<span id="pymanager-offline"></span><h3><span class="section-number">4.1.6. </span>Offline installs<a class="headerlink" href="#offline-installs" title="Link to this heading">¶</a></h3>
|
||
<p>To perform offline installs of Python, you will need to first create an offline
|
||
index on a machine that has network access.</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$> py install --download=<PATH> ... <TAG>...
|
||
</pre></div>
|
||
</div>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">--download=<PATH></span></code> option will download the packages for the listed tags
|
||
and create a directory containing them and an <code class="docutils literal notranslate"><span class="pre">index.json</span></code> file suitable for
|
||
later installation. This entire directory can be moved to the offline machine
|
||
and used to install one or more of the bundled runtimes:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$> py install --source="<PATH>\index.json" <TAG>...
|
||
</pre></div>
|
||
</div>
|
||
<p>The Python install manager can be installed by downloading its installer and
|
||
moving it to another machine before installing.</p>
|
||
<p>Alternatively, the ZIP files in an offline index directory can simply be
|
||
transferred to another machine and extracted. This will not register the install
|
||
in any way, and so it must be launched by directly referencing the executables
|
||
in the extracted directory, but it is sometimes a preferable approach in cases
|
||
where installing the Python install manager is not possible or convenient.</p>
|
||
<p>In this way, Python runtimes can be installed and managed on a machine without
|
||
access to the internet.</p>
|
||
</section>
|
||
<section id="uninstalling-runtimes">
|
||
<h3><span class="section-number">4.1.7. </span>Uninstalling runtimes<a class="headerlink" href="#uninstalling-runtimes" title="Link to this heading">¶</a></h3>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$> py uninstall [-y|--yes] <TAG>...
|
||
</pre></div>
|
||
</div>
|
||
<p>Runtimes may be removed using the <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">uninstall</span></code> command. One or more tags
|
||
must be specified. Ranges are not supported here.</p>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">--yes</span></code> option bypasses the confirmation prompt before uninstalling.</p>
|
||
<p>Instead of passing tags individually, the <code class="docutils literal notranslate"><span class="pre">--purge</span></code> option may be specified.
|
||
This will remove all runtimes managed by the Python install manager, including
|
||
cleaning up the Start menu, registry, and any download caches. Runtimes that
|
||
were not installed by the Python install manager will not be impacted, and
|
||
neither will manually created configuration files.</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$> py uninstall [-y|--yes] --purge
|
||
</pre></div>
|
||
</div>
|
||
<p>The Python install manager can be uninstalled through the Windows “Installed
|
||
apps” settings page. This does not remove any runtimes, and they will still be
|
||
usable, though the global <code class="docutils literal notranslate"><span class="pre">python</span></code> and <code class="docutils literal notranslate"><span class="pre">py</span></code> commands will be removed.
|
||
Reinstalling the Python install manager will allow you to manage these runtimes
|
||
again. To completely clean up all Python runtimes, run with <code class="docutils literal notranslate"><span class="pre">--purge</span></code> before
|
||
uninstalling the Python install manager.</p>
|
||
</section>
|
||
<section id="configuration">
|
||
<span id="pymanager-config"></span><h3><span class="section-number">4.1.8. </span>Configuration<a class="headerlink" href="#configuration" title="Link to this heading">¶</a></h3>
|
||
<p>Python install manager is configured with a hierarchy of configuration files,
|
||
environment variables, command-line options, and registry settings. In general,
|
||
configuration files have the ability to configure everything, including the
|
||
location of other configuration files, while registry settings are
|
||
administrator-only and will override configuration files. Command-line options
|
||
override all other settings, but not every option is available.</p>
|
||
<p>This section will describe the defaults, but be aware that modified or
|
||
overridden installs may resolve settings differently.</p>
|
||
<p>A global configuration file may be configured by an administrator, and would be
|
||
read first. The user configuration file is stored at
|
||
<code class="file docutils literal notranslate"><span class="pre">%AppData%\Python\pymanager.json</span></code>
|
||
(note that this location is under <code class="docutils literal notranslate"><span class="pre">Roaming</span></code>, not <code class="docutils literal notranslate"><span class="pre">Local</span></code>) and is read next,
|
||
overwriting any settings from earlier files. An additional configuration file
|
||
may be specified as the <code class="docutils literal notranslate"><span class="pre">PYTHON_MANAGER_CONFIG</span></code> environment variable or the
|
||
<code class="docutils literal notranslate"><span class="pre">--config</span></code> command line option (but not both).
|
||
These locations may be modified by administrative customization options listed
|
||
later.</p>
|
||
<p>The following settings are those that are considered likely to be modified in
|
||
normal use. Later sections list those that are intended for administrative
|
||
customization.</p>
|
||
<p class="rubric">Standard configuration options</p>
|
||
<table class="docutils align-default">
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>Config Key</p></th>
|
||
<th class="head"><p>Environment Variable</p></th>
|
||
<th class="head"><p>Description</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">default_tag</span></code></p></td>
|
||
<td><dl class="std envvar">
|
||
<dt class="sig sig-object std" id="envvar-PYTHON_MANAGER_DEFAULT">
|
||
<span class="sig-name descname"><span class="pre">PYTHON_MANAGER_DEFAULT</span></span><a class="headerlink" href="#envvar-PYTHON_MANAGER_DEFAULT" title="Link to this definition">¶</a></dt>
|
||
<dd></dd></dl>
|
||
|
||
</td>
|
||
<td><p>The preferred default version to launch or install.
|
||
By default, this is interpreted as the most recent non-prerelease version
|
||
from the CPython team.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">default_platform</span></code></p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">PYTHON_MANAGER_DEFAULT_PLATFORM</span></code></p></td>
|
||
<td><p>The preferred default platform to launch or install.
|
||
This is treated as a suffix to the specified tag, such that <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">-V:3.14</span></code>
|
||
would prefer an install for <code class="docutils literal notranslate"><span class="pre">3.14-64</span></code> if it exists
|
||
(and <code class="docutils literal notranslate"><span class="pre">default_platform</span></code> is <code class="docutils literal notranslate"><span class="pre">-64</span></code>),
|
||
but will use <code class="docutils literal notranslate"><span class="pre">3.14</span></code> if no tagged install exists.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">logs_dir</span></code></p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">PYTHON_MANAGER_LOGS</span></code></p></td>
|
||
<td><p>The location where log files are written.
|
||
By default, <code class="file docutils literal notranslate"><span class="pre">%TEMP%</span></code>.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">automatic_install</span></code></p></td>
|
||
<td><dl class="std envvar">
|
||
<dt class="sig sig-object std" id="envvar-PYTHON_MANAGER_AUTOMATIC_INSTALL">
|
||
<span class="sig-name descname"><span class="pre">PYTHON_MANAGER_AUTOMATIC_INSTALL</span></span><a class="headerlink" href="#envvar-PYTHON_MANAGER_AUTOMATIC_INSTALL" title="Link to this definition">¶</a></dt>
|
||
<dd></dd></dl>
|
||
|
||
</td>
|
||
<td><p>True to allow automatic installs when using <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">exec</span></code> to launch (or
|
||
<code class="docutils literal notranslate"><span class="pre">py</span></code> when no runtimes are installed yet).
|
||
Other commands will not automatically install, regardless of this
|
||
setting.
|
||
By default, true.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">include_unmanaged</span></code></p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">PYTHON_MANAGER_INCLUDE_UNMANAGED</span></code></p></td>
|
||
<td><p>True to allow listing and launching runtimes that were not installed
|
||
by the Python install manager, or false to exclude them.
|
||
By default, true.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">shebang_can_run_anything</span></code></p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">PYTHON_MANAGER_SHEBANG_CAN_RUN_ANYTHING</span></code></p></td>
|
||
<td><p>True to allow shebangs in <code class="docutils literal notranslate"><span class="pre">.py</span></code> files to launch applications other than
|
||
Python runtimes, or false to prevent it.
|
||
By default, true.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">shebang_templates</span></code></p></td>
|
||
<td><p>(none)</p></td>
|
||
<td><p>Mapping from shebang line template to alternative command, such as
|
||
<code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">-V:<tag></span></code> or a substitute string.
|
||
See <a class="reference internal" href="#pymanager-shebang"><span class="std std-ref">Shebang lines</span></a> for more details.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">log_level</span></code></p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">PYMANAGER_VERBOSE</span></code>, <code class="docutils literal notranslate"><span class="pre">PYMANAGER_DEBUG</span></code></p></td>
|
||
<td><p>Set the default level of output (0-50).
|
||
By default, 20.
|
||
Lower values produce more output.
|
||
The environment variables are boolean, and may produce additional
|
||
output during startup that is later suppressed by other configuration.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">confirm</span></code></p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">PYTHON_MANAGER_CONFIRM</span></code></p></td>
|
||
<td><p>True to confirm certain actions before taking them (such as uninstall),
|
||
or false to skip the confirmation.
|
||
By default, true.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">install.source</span></code></p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">PYTHON_MANAGER_SOURCE_URL</span></code></p></td>
|
||
<td><p>Override the index feed to obtain new installs from.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">install.enable_entrypoints</span></code></p></td>
|
||
<td><p>(none)</p></td>
|
||
<td><p>True to generate global commands for installed packages (such as
|
||
<code class="docutils literal notranslate"><span class="pre">pip.exe</span></code>). These are defined by the packages themselves.
|
||
If set to false, only the Python interpreter has global commands created.
|
||
By default, true. You should run <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">install</span> <span class="pre">--refresh</span></code> after changing
|
||
this setting.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">list.format</span></code></p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">PYTHON_MANAGER_LIST_FORMAT</span></code></p></td>
|
||
<td><p>Specify the default format used by the <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">list</span></code> command.
|
||
By default, <code class="docutils literal notranslate"><span class="pre">table</span></code>.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">install_dir</span></code></p></td>
|
||
<td><p>(none)</p></td>
|
||
<td><p>Specify the root directory that runtimes will be installed into.
|
||
If you change this setting, previously installed runtimes will not be
|
||
usable unless you move them to the new location.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">global_dir</span></code></p></td>
|
||
<td><p>(none)</p></td>
|
||
<td><p>Specify the directory where global commands (such as <code class="docutils literal notranslate"><span class="pre">python3.14.exe</span></code>
|
||
and <code class="docutils literal notranslate"><span class="pre">pip.exe</span></code>) are stored.
|
||
This directory should be added to your <span class="target" id="index-5"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code> to make the
|
||
commands available from your terminal.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">download_dir</span></code></p></td>
|
||
<td><p>(none)</p></td>
|
||
<td><p>Specify the directory where downloaded files are stored.
|
||
This directory is a temporary cache, and can be cleaned up from time to
|
||
time.</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>Dotted names should be nested inside JSON objects, for example, <code class="docutils literal notranslate"><span class="pre">list.format</span></code>
|
||
would be specified as <code class="docutils literal notranslate"><span class="pre">{"list":</span> <span class="pre">{"format":</span> <span class="pre">"table"}}</span></code>.</p>
|
||
</section>
|
||
<section id="shebang-lines">
|
||
<span id="pymanager-shebang"></span><h3><span class="section-number">4.1.9. </span>Shebang lines<a class="headerlink" href="#shebang-lines" title="Link to this heading">¶</a></h3>
|
||
<p>If the first line of a script file starts with <code class="docutils literal notranslate"><span class="pre">#!</span></code>, it is known as a
|
||
“shebang” line. Linux and other Unix like operating systems have native
|
||
support for such lines and they are commonly used on such systems to indicate
|
||
how a script should be executed. The <code class="docutils literal notranslate"><span class="pre">python</span></code> and <code class="docutils literal notranslate"><span class="pre">py</span></code> commands allow the
|
||
same facilities to be used with Python scripts on Windows.</p>
|
||
<p>To allow shebang lines in Python scripts to be portable between Unix and
|
||
Windows, a number of ‘virtual’ commands are supported to specify which
|
||
interpreter to use. The supported virtual commands are:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">/usr/bin/env</span> <span class="pre"><ALIAS></span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">/usr/bin/env</span> <span class="pre">-S</span> <span class="pre"><ALIAS></span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">/usr/bin/<ALIAS></span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">/usr/local/bin/<ALIAS></span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre"><ALIAS></span></code></p></li>
|
||
</ul>
|
||
<p>For example, if the first line of your script starts with</p>
|
||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="ch">#! /usr/bin/python</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The default Python or an active virtual environment will be located and used.
|
||
As many Python scripts written to work on Unix will already have this line,
|
||
you should find these scripts can be used by the launcher without modification.
|
||
If you are writing a new script on Windows which you hope will be useful on
|
||
Unix, you should use one of the shebang lines starting with <code class="docutils literal notranslate"><span class="pre">/usr</span></code>.</p>
|
||
<p>Any of the above virtual commands can have <code class="docutils literal notranslate"><span class="pre"><ALIAS></span></code> replaced by an alias from
|
||
an installed runtime. That is, any command generated in the global aliases
|
||
directory (which you may have added to your <span class="target" id="index-6"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code> environment variable)
|
||
can be used in a shebang, even if it is not on your <span class="target" id="index-7"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code>. This allows
|
||
the use of shebangs like <code class="docutils literal notranslate"><span class="pre">/usr/bin/python3.12</span></code> to select a particular runtime.</p>
|
||
<p>If no runtimes are installed, or if automatic installation is enabled, the
|
||
requested runtime will be installed if necessary. See <a class="reference internal" href="#pymanager-config"><span class="std std-ref">Configuration</span></a>
|
||
for information about configuration settings.</p>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">/usr/bin/env</span></code> form of shebang line will also search the <span class="target" id="index-8"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code>
|
||
environment variable for unrecognized commands. This corresponds to the
|
||
behaviour of the Unix <code class="docutils literal notranslate"><span class="pre">env</span></code> program, which performs the same search, but
|
||
prefers launching known Python commands. A warning may be displayed when
|
||
searching for arbitrary executables, and this search may be disabled by the
|
||
<code class="docutils literal notranslate"><span class="pre">shebang_can_run_anything</span></code> configuration option.</p>
|
||
<p>Shebang lines that do not match any of patterns are treated as <em>Windows</em>
|
||
executable paths that are absolute or relative to the directory containing the
|
||
script file. This is a convenience for Windows-only scripts, such as those
|
||
generated by an installer, since the behavior is not compatible with Unix-style
|
||
shells. These paths may be quoted, and may include multiple arguments, after
|
||
which the path to the script and any additional arguments will be appended.
|
||
This functionality may be disabled by the <code class="docutils literal notranslate"><span class="pre">shebang_can_run_anything</span></code>
|
||
configuration option.</p>
|
||
<p>Since version 26.3 of the Python install manager, custom shebang templates may
|
||
be added to your configuration file. Add the <code class="docutils literal notranslate"><span class="pre">shebang_templates</span></code> object with
|
||
one member for each template (the string to match) and the command to use when
|
||
the template is matched. Most commands should be <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">-V:<tag></span></code> (or <code class="docutils literal notranslate"><span class="pre">pyw</span></code>) to
|
||
launch one of your installed runtimes. The <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">-3.<version></span></code> form is also
|
||
allowed, as is a plain <code class="docutils literal notranslate"><span class="pre">py</span></code> to launch the default. No other arguments are
|
||
supported.</p>
|
||
<div class="highlight-json5 notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nv">"shebang_templates"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nv">"/usr/bin/python"</span><span class="p">:</span><span class="w"> </span><span class="s">"py"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nv">"/usr/bin/my_custom_python"</span><span class="p">:</span><span class="w"> </span><span class="s">"py -V:MyCustomPython/3"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>If the substitute command is not <code class="docutils literal notranslate"><span class="pre">py</span></code> or <code class="docutils literal notranslate"><span class="pre">pyw</span></code>, it will be written back into
|
||
the shebang and regular handling continues. If launching arbitrary executables
|
||
is permitted, then providing a full path will allow you to redirect from Python
|
||
to any executable. The template should match either the entire line (ignoring
|
||
leading and trailing whitespace), or up to the first space in the shebang line.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>The behaviour of shebangs in the Python install manager is subtly different
|
||
from the previous <code class="docutils literal notranslate"><span class="pre">py.exe</span></code> launcher, and the old configuration options no
|
||
longer apply. If you are specifically reliant on the old behaviour or
|
||
configuration, we recommend installing the <a class="reference external" href="https://www.python.org/ftp/python/3.14.0/win32/launcher.msi">legacy launcher</a>. The legacy
|
||
launcher’s <code class="docutils literal notranslate"><span class="pre">py</span></code> command will override PyManager’s one by default, and you
|
||
will need to use <code class="docutils literal notranslate"><span class="pre">pymanager</span></code> commands for installing and uninstalling.</p>
|
||
</div>
|
||
</section>
|
||
<section id="advanced-installation">
|
||
<span id="pymanager-advancedinstall"></span><h3><span class="section-number">4.1.10. </span>Advanced installation<a class="headerlink" href="#advanced-installation" title="Link to this heading">¶</a></h3>
|
||
<p>For situations where an MSIX cannot be installed, such as some older
|
||
administrative distribution platforms, there is an MSI available from the
|
||
python.org downloads page. This MSI has no user interface, and can only perform
|
||
per-machine installs to its default location in Program Files. It will attempt
|
||
to modify the system <span class="target" id="index-9"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code> environment variable to include this install
|
||
location, but be sure to validate this on your configuration.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Windows Server 2019 is the only version of Windows that CPython supports that
|
||
does not support MSIX. For Windows Server 2019, you should use the MSI.</p>
|
||
</div>
|
||
<p>Be aware that the MSI package does not bundle any runtimes, and so is not
|
||
suitable for installs into offline environments without also creating an offline
|
||
install index. See <a class="reference internal" href="#pymanager-offline"><span class="std std-ref">Offline installs</span></a> and <a class="reference internal" href="#pymanager-admin-config"><span class="std std-ref">Administrative configuration</span></a>
|
||
for information on handling these scenarios.</p>
|
||
<p>Runtimes installed by the MSI are shared with those installed by the MSIX, and
|
||
are all per-user only. The Python install manager does not support installing
|
||
runtimes per-machine. To emulate a per-machine install, you can use <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">install</span>
|
||
<span class="pre">--target=<shared</span> <span class="pre">location></span></code> as administrator and add your own system-wide
|
||
modifications to <span class="target" id="index-10"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code>, the registry, or the Start menu.</p>
|
||
<p>When the MSIX is installed, but commands are not available in the <span class="target" id="index-11"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code>
|
||
environment variable, they can be found under
|
||
<code class="file docutils literal notranslate"><span class="pre">%LocalAppData%\Microsoft\WindowsApps\PythonSoftwareFoundation.PythonManager_3847v3x7pw1km</span></code>
|
||
or
|
||
<code class="file docutils literal notranslate"><span class="pre">%LocalAppData%\Microsoft\WindowsApps\PythonSoftwareFoundation.PythonManager_qbz5n2kfra8p0</span></code>,
|
||
depending on whether it was installed from python.org or through the Windows
|
||
Store. Attempting to run the executable directly from Program Files is not
|
||
recommended.</p>
|
||
<p>To programmatically install the Python install manager, it is easiest to use
|
||
WinGet, which is included with all supported versions of Windows:</p>
|
||
<div class="highlight-powershell notranslate"><div class="highlight"><pre><span></span><span class="p">$></span> <span class="n">winget</span> <span class="n">install</span> <span class="n">9NQ7512CXL7T</span> <span class="n">-e</span> <span class="p">-</span><span class="n">-accept-package-agreements</span> <span class="p">-</span><span class="n">-disable-interactivity</span>
|
||
|
||
<span class="c"># Optionally run the configuration checker and accept all changes</span>
|
||
<span class="p">$></span> <span class="n">py</span> <span class="n">install</span> <span class="p">-</span><span class="n">-configure</span> <span class="n">-y</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>To download the Python install manager and install on another machine, the
|
||
following WinGet command will download the required files from the Store to your
|
||
Downloads directory (add <code class="docutils literal notranslate"><span class="pre">-d</span> <span class="pre"><location></span></code> to customize the output location).
|
||
This also generates a YAML file that appears to be unnecessary, as the
|
||
downloaded MSIX can be installed by launching or using the commands below.</p>
|
||
<div class="highlight-powershell notranslate"><div class="highlight"><pre><span></span><span class="p">$></span> <span class="n">winget</span> <span class="n">download</span> <span class="n">9NQ7512CXL7T</span> <span class="n">-e</span> <span class="p">-</span><span class="n">-skip-license</span> <span class="p">-</span><span class="n">-accept-package-agreements</span> <span class="p">-</span><span class="n">-accept-source-agreements</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>To programmatically install or uninstall an MSIX using only PowerShell, the
|
||
<a class="reference external" href="https://learn.microsoft.com/powershell/module/appx/add-appxpackage">Add-AppxPackage</a> and <a class="reference external" href="https://learn.microsoft.com/powershell/module/appx/remove-appxpackage">Remove-AppxPackage</a> PowerShell cmdlets are recommended:</p>
|
||
<div class="highlight-powershell notranslate"><div class="highlight"><pre><span></span><span class="p">$></span> <span class="nb">Add-AppxPackage</span> <span class="n">C</span><span class="p">:\</span><span class="n">Downloads</span><span class="p">\</span><span class="n">python-manager</span><span class="p">-</span><span class="n">25</span><span class="p">.</span><span class="n">0</span><span class="p">.</span><span class="n">msix</span>
|
||
<span class="p">...</span>
|
||
<span class="p">$></span> <span class="nb">Get-AppxPackage</span> <span class="n">PythonSoftwareFoundation</span><span class="p">.</span><span class="n">PythonManager</span> <span class="p">|</span> <span class="nb">Remove-AppxPackage</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The latest release can be downloaded and installed by Windows by passing the
|
||
AppInstaller file to the Add-AppxPackage command. This installs using the MSIX
|
||
on python.org, and is only recommended for cases where installing via the Store
|
||
(interactively or using WinGet) is not possible.</p>
|
||
<div class="highlight-powershell notranslate"><div class="highlight"><pre><span></span><span class="p">$></span> <span class="nb">Add-AppxPackage</span> <span class="n">-AppInstallerFile</span> <span class="n">https</span><span class="p">://</span><span class="n">www</span><span class="p">.</span><span class="n">python</span><span class="p">.</span><span class="n">org</span><span class="p">/</span><span class="n">ftp</span><span class="p">/</span><span class="n">python</span><span class="p">/</span><span class="n">pymanager</span><span class="p">/</span><span class="n">pymanager</span><span class="p">.</span><span class="n">appinstaller</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Other tools and APIs may also be used to provision an MSIX package for all users
|
||
on a machine, but Python does not consider this a supported scenario. We suggest
|
||
looking into the PowerShell <a class="reference external" href="https://learn.microsoft.com/powershell/module/dism/add-appxprovisionedpackage">Add-AppxProvisionedPackage</a> cmdlet, the native
|
||
Windows <a class="reference external" href="https://learn.microsoft.com/uwp/api/windows.management.deployment.packagemanager">PackageManager</a> class, or the documentation and support for your
|
||
deployment tool.</p>
|
||
<p>Regardless of the install method, users will still need to install their own
|
||
copies of Python itself, as there is no way to trigger those installs without
|
||
being a logged in user. When using the MSIX, the latest version of Python will
|
||
be available for all users to install without network access.</p>
|
||
<p>Note that the MSIX downloadable from the Store and from the Python website are
|
||
subtly different and cannot be installed at the same time. Wherever possible,
|
||
we suggest using the above WinGet commands to download the package from the
|
||
Store to reduce the risk of setting up conflicting installs. There are no
|
||
licensing restrictions on the Python install manager that would prevent using
|
||
the Store package in this way.</p>
|
||
</section>
|
||
<section id="administrative-configuration">
|
||
<span id="pymanager-admin-config"></span><h3><span class="section-number">4.1.11. </span>Administrative configuration<a class="headerlink" href="#administrative-configuration" title="Link to this heading">¶</a></h3>
|
||
<p>There are a number of options that may be useful for administrators to override
|
||
configuration of the Python install manager. These can be used to provide local
|
||
caching, disable certain shortcut types, override bundled content. All of the
|
||
above configuration options may be set, as well as those below.</p>
|
||
<p>Configuration options may be overridden in the registry by setting values under
|
||
<code class="file docutils literal notranslate"><span class="pre">HKEY_LOCAL_MACHINE\Software\Policies\Python\PyManager</span></code>, where the
|
||
value name matches the configuration key and the value type is <code class="docutils literal notranslate"><span class="pre">REG_SZ</span></code>. Note
|
||
that this key can itself be customized, but only by modifying the core config
|
||
file distributed with the Python install manager. We recommend, however, that
|
||
registry values are used only to set <code class="docutils literal notranslate"><span class="pre">base_config</span></code> to a JSON file containing
|
||
the full set of overrides. Registry key overrides will replace any other
|
||
configured setting, while <code class="docutils literal notranslate"><span class="pre">base_config</span></code> allows users to further modify
|
||
settings they may need.</p>
|
||
<p>Note that most settings with environment variables support those variables
|
||
because their default setting specifies the variable. If you override them, the
|
||
environment variable will no longer work, unless you override it with another
|
||
one. For example, the default value of <code class="docutils literal notranslate"><span class="pre">confirm</span></code> is literally
|
||
<code class="docutils literal notranslate"><span class="pre">%PYTHON_MANAGER_CONFIRM%</span></code>, which will resolve the variable at load time. If
|
||
you override the value to <code class="docutils literal notranslate"><span class="pre">yes</span></code>, then the environment variable will no longer
|
||
be used. If you override the value to <code class="docutils literal notranslate"><span class="pre">%CONFIRM%</span></code>, then that environment
|
||
variable will be used instead.</p>
|
||
<p>Configuration settings that are paths are interpreted as relative to the
|
||
directory containing the configuration file that specified them.</p>
|
||
<p class="rubric">Administrative configuration options</p>
|
||
<table class="docutils align-default">
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>Config Key</p></th>
|
||
<th class="head"><p>Description</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">base_config</span></code></p></td>
|
||
<td><p>The highest priority configuration file to read.
|
||
Note that only the built-in configuration file and the registry can
|
||
modify this setting.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">user_config</span></code></p></td>
|
||
<td><p>The second configuration file to read.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">additional_config</span></code></p></td>
|
||
<td><p>The third configuration file to read.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">registry_override_key</span></code></p></td>
|
||
<td><p>Registry location to check for overrides.
|
||
Note that only the built-in configuration file can modify this setting.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">bundled_dir</span></code></p></td>
|
||
<td><p>Read-only directory containing locally cached files.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">install.fallback_source</span></code></p></td>
|
||
<td><p>Path or URL to an index to consult when the main index cannot be accessed.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">install.enable_shortcut_kinds</span></code></p></td>
|
||
<td><p>Comma-separated list of shortcut kinds to allow (e.g. <code class="docutils literal notranslate"><span class="pre">"pep514,start"</span></code>).
|
||
Enabled shortcuts may still be disabled by <code class="docutils literal notranslate"><span class="pre">disable_shortcut_kinds</span></code>.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">install.disable_shortcut_kinds</span></code></p></td>
|
||
<td><p>Comma-separated list of shortcut kinds to exclude
|
||
(e.g. <code class="docutils literal notranslate"><span class="pre">"pep514,start"</span></code>).
|
||
Disabled shortcuts are not reactivated by <code class="docutils literal notranslate"><span class="pre">enable_shortcut_kinds</span></code>.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">install.hard_link_entrypoints</span></code></p></td>
|
||
<td><p>True to use hard links for global shortcuts to save disk space. If false,
|
||
each shortcut executable is copied instead. After changing this setting,
|
||
you must run <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">install</span> <span class="pre">--refresh</span> <span class="pre">--force</span></code> to update existing
|
||
commands.
|
||
By default, true. Disabling this may be necessary for troubleshooting or
|
||
systems that have issues with file links.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">pep514_root</span></code></p></td>
|
||
<td><p>Registry location to read and write PEP 514 entries into.
|
||
By default, <code class="file docutils literal notranslate"><span class="pre">HKEY_CURRENT_USER\Software\Python</span></code>.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">start_folder</span></code></p></td>
|
||
<td><p>Start menu folder to write shortcuts into.
|
||
By default, <code class="docutils literal notranslate"><span class="pre">Python</span></code>.
|
||
This path is relative to the user’s Programs folder.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">virtual_env</span></code></p></td>
|
||
<td><p>Path to the active virtual environment.
|
||
By default, this is <code class="docutils literal notranslate"><span class="pre">%VIRTUAL_ENV%</span></code>, but may be set empty
|
||
to disable venv detection.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">shebang_can_run_anything_silently</span></code></p></td>
|
||
<td><p>True to suppress visible warnings when a shebang launches an application
|
||
other than a Python runtime.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">source_settings</span></code></p></td>
|
||
<td><p>A mapping from source URL to settings specific to that index.
|
||
When multiple configuration files include this section, URL settings are
|
||
added or overwritten, but individual settings are not merged.
|
||
These settings are currently only for <a class="reference internal" href="#pymanager-index-signatures"><span class="std std-ref">index signatures</span></a>.</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</section>
|
||
<section id="installing-free-threaded-binaries">
|
||
<span id="install-freethreaded-windows"></span><h3><span class="section-number">4.1.12. </span>Installing free-threaded binaries<a class="headerlink" href="#installing-free-threaded-binaries" title="Link to this heading">¶</a></h3>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.13.</span></p>
|
||
</div>
|
||
<p>Pre-built distributions of the free-threaded build are available
|
||
by installing tags with the <code class="docutils literal notranslate"><span class="pre">t</span></code> suffix.</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$> py install 3.14t
|
||
$> py install 3.14t-arm64
|
||
$> py install 3.14t-32
|
||
</pre></div>
|
||
</div>
|
||
<p>This will install and register as normal. If you have no other runtimes
|
||
installed, then <code class="docutils literal notranslate"><span class="pre">python</span></code> will launch this one. Otherwise, you will need to use
|
||
<code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">-V:3.14t</span> <span class="pre">...</span></code> or, if you have added the global aliases directory to your
|
||
<span class="target" id="index-12"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code> environment variable, the <code class="docutils literal notranslate"><span class="pre">python3.14t.exe</span></code> commands.</p>
|
||
</section>
|
||
<section id="index-signatures">
|
||
<span id="pymanager-index-signatures"></span><h3><span class="section-number">4.1.13. </span>Index signatures<a class="headerlink" href="#index-signatures" title="Link to this heading">¶</a></h3>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 26.2.</span></p>
|
||
</div>
|
||
<p>Index files may be signed to detect tampering. A signature is a catalog file
|
||
at the same URL as the index with <code class="docutils literal notranslate"><span class="pre">.cat</span></code> added to the filename. The catalog
|
||
file should contain the hash of its matching index file, and should be signed
|
||
with a valid Authenticode signature. This allows standard tooling (on Windows)
|
||
to generate a signature, and any certificate may be used as long as the client
|
||
operating system already trusts its certification authority (root CA).</p>
|
||
<p>Index signatures are only downloaded and checked when the local configuration’s
|
||
<code class="docutils literal notranslate"><span class="pre">source_settings</span></code> section includes the index URL and <code class="docutils literal notranslate"><span class="pre">requires_signature</span></code> is
|
||
true, or the index JSON contains <code class="docutils literal notranslate"><span class="pre">requires_signature</span></code> set to true. When the
|
||
setting exists in local configuration, even when false, settings in the index
|
||
are ignored.</p>
|
||
<p>As well as requiring a valid signature, the <code class="docutils literal notranslate"><span class="pre">required_root_subject</span></code> and
|
||
<code class="docutils literal notranslate"><span class="pre">required_publisher_subject</span></code> settings can further restrict acceptable
|
||
signatures based on the certificate Subject fields. Any attribute specified in
|
||
the configuration must match the attribute in the certificate (additional
|
||
attributes in the certificate are ignored). Typical attributes are <code class="docutils literal notranslate"><span class="pre">CN=</span></code> for
|
||
the common name, <code class="docutils literal notranslate"><span class="pre">O=</span></code> for the organizational unit, and <code class="docutils literal notranslate"><span class="pre">C=</span></code> for the
|
||
publisher’s country.</p>
|
||
<p>Finally, the <code class="docutils literal notranslate"><span class="pre">required_publisher_eku</span></code> setting allows requiring that a specific
|
||
Enhanced Key Usage (EKU) has been assigned to the publisher certificate. For
|
||
example, the EKU <code class="docutils literal notranslate"><span class="pre">1.3.6.1.5.5.7.3.3</span></code> indicates that the certificate was
|
||
intended for code signing (as opposed to server or client authentication).
|
||
In combination with a specific root CA, this provides another mechanism to
|
||
verify a legitimate signature.</p>
|
||
<p>This is an example <code class="docutils literal notranslate"><span class="pre">source_settings</span></code> section from a configuration file. In
|
||
this case, the publisher of the feed is uniquely identified by the combination
|
||
of the Microsoft Identity Verification root and the EKU assigned by that root.
|
||
The signature for this case would be found at
|
||
<code class="docutils literal notranslate"><span class="pre">https://www.python.org/ftp/python/index-windows.json.cat</span></code>.</p>
|
||
<div class="highlight-json5 notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nv">"source_settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nv">"https://www.python.org/ftp/python/index-windows.json"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nv">"requires_signature"</span><span class="p">:</span><span class="w"> </span><span class="k">true</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nv">"required_root_subject"</span><span class="p">:</span><span class="w"> </span><span class="s">"CN=Microsoft Identity Verification Root Certificate Authority 2020"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nv">"required_publisher_subject"</span><span class="p">:</span><span class="w"> </span><span class="s">"CN=Python Software Foundation"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nv">"required_publisher_eku"</span><span class="p">:</span><span class="w"> </span><span class="s">"1.3.6.1.4.1.311.97.608394634.79987812.305991749.578777327"</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The same settings could be specified in the <code class="docutils literal notranslate"><span class="pre">index.json</span></code> file instead. In this
|
||
case, the root and EKU are omitted, meaning that the signature must be valid and
|
||
have a specific common name in the publisher’s certificate, but no other checks
|
||
are used.</p>
|
||
<div class="highlight-json5 notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nv">"requires_signature"</span><span class="p">:</span><span class="w"> </span><span class="k">true</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nv">"required_publisher_subject"</span><span class="p">:</span><span class="w"> </span><span class="s">"CN=Python Software Foundation"</span><span class="p">,</span>
|
||
<span class="w"> </span><span class="nv">"versions"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
||
<span class="w"> </span><span class="c1">// ...</span>
|
||
<span class="w"> </span><span class="p">]</span>
|
||
<span class="p">}</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>When settings from inside a feed are used, the user is notified and the settings
|
||
are shown in the log file or verbose output. It is recommended to copy these
|
||
settings into a local configuration file for feeds that will be used frequently,
|
||
so that unauthorised modifications to the feed cannot disable verification.</p>
|
||
<p>It is not possible to override the location of the signature file in the feed or
|
||
through a configuration file. Administrators can provide their own
|
||
<code class="docutils literal notranslate"><span class="pre">source_settings</span></code> in a mandatory configuration file (see
|
||
<a class="reference internal" href="#pymanager-admin-config"><span class="std std-ref">Administrative configuration</span></a>).</p>
|
||
<p>If signature validation fails, you will be notified and prompted to continue.
|
||
When interactive confirmation is not allowed (for example, because <code class="docutils literal notranslate"><span class="pre">--yes</span></code> was
|
||
specified), it will always abort. To use a feed with invalid configuration in
|
||
this scenario, you must provide a configuration file that disables signature
|
||
checking for that feed.</p>
|
||
<div class="highlight-json5 notranslate"><div class="highlight"><pre><span></span><span class="s">"source_settings"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nv">"https://www.example.com/feed-with-invalid-signature.json"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
||
<span class="w"> </span><span class="nv">"requires_signature"</span><span class="p">:</span><span class="w"> </span><span class="k">false</span>
|
||
<span class="w"> </span><span class="p">}</span>
|
||
<span class="p">}</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="proxy-settings">
|
||
<h3><span class="section-number">4.1.14. </span>Proxy settings<a class="headerlink" href="#proxy-settings" title="Link to this heading">¶</a></h3>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 26.4.</span></p>
|
||
</div>
|
||
<p>By default, the Python install manager will use your system-wide proxy settings,
|
||
including automatic authentication. For most users, this behaves the same as
|
||
your browser and other applications.</p>
|
||
<p>To override the settings, use the <code class="docutils literal notranslate"><span class="pre">NO_PROXY</span></code>, <code class="docutils literal notranslate"><span class="pre">HTTP_PROXY</span></code> and
|
||
<code class="docutils literal notranslate"><span class="pre">HTTPS_PROXY</span></code> environment variables. These should be set in the terminal
|
||
session before using the Python install manager. Other applications may also
|
||
use the variables, so use caution before setting them globally for your entire
|
||
machine.</p>
|
||
<p>Setting <code class="docutils literal notranslate"><span class="pre">NO_PROXY</span></code> to any non-empty value will disable the use of any proxy.
|
||
Use this to bypass your system’s default proxy setting and attempt to access the
|
||
index server directly.</p>
|
||
<p>Setting <code class="docutils literal notranslate"><span class="pre">HTTPS_PROXY</span></code> to a string like <code class="docutils literal notranslate"><span class="pre">example.com:8080</span></code> will connect to
|
||
that proxy server for all HTTPS connections. For the default index, all
|
||
connections will be using HTTPS, and so this is the usual setting to override.</p>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">HTTP_PROXY</span></code> variable may be needed if you are using a private index
|
||
server that does not use encrypted connections, but does require the default
|
||
proxy server to be overridden. It follows the same format as <code class="docutils literal notranslate"><span class="pre">HTTPS_PROXY</span></code>.</p>
|
||
<p>Credentials may be embedded in either setting, however, when <code class="docutils literal notranslate"><span class="pre">HTTPS_PROXY</span></code> has
|
||
credentials embedded they will be used in preference to other credentials. Only
|
||
one set of credentials will be used for both types of proxy.</p>
|
||
</section>
|
||
<section id="troubleshooting">
|
||
<span id="pymanager-troubleshoot"></span><h3><span class="section-number">4.1.15. </span>Troubleshooting<a class="headerlink" href="#troubleshooting" title="Link to this heading">¶</a></h3>
|
||
<p>If your Python install manager does not seem to be working correctly, please
|
||
work through these tests and fixes to see if it helps. If not, please report an
|
||
issue at <a class="reference external" href="https://github.com/python/pymanager/issues">our bug tracker</a>,
|
||
including any relevant log files (written to your <code class="file docutils literal notranslate"><span class="pre">%TEMP%</span></code> directory by
|
||
default).</p>
|
||
<p class="rubric">Troubleshooting</p>
|
||
<table class="docutils align-default">
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>Symptom</p></th>
|
||
<th class="head"><p>Things to try</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">python</span></code> gives me a “command not found” error or opens the Store app
|
||
when I type it in my terminal.</p></td>
|
||
<td><p>Did you <a class="reference internal" href="#pymanager"><span class="std std-ref">install the Python install manager</span></a>?</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td></td>
|
||
<td><p>Click Start, open “Manage app execution aliases”, and check that the
|
||
aliases for “Python (default)” are enabled.
|
||
If they already are, try disabling and re-enabling to refresh the command.
|
||
The “Python (default windowed)” and “Python install manager” commands
|
||
may also need refreshing.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td></td>
|
||
<td><p>Check that the <code class="docutils literal notranslate"><span class="pre">py</span></code> and <code class="docutils literal notranslate"><span class="pre">pymanager</span></code> commands work.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td></td>
|
||
<td><p>Ensure your <span class="target" id="index-13"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code> variable contains the entry for
|
||
<code class="docutils literal notranslate"><span class="pre">%UserProfile%\AppData\Local\Microsoft\WindowsApps</span></code>.
|
||
The operating system includes this entry once by default, after other
|
||
user paths. If removed, shortcuts will not be found.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">py</span></code> gives me a “command not found” error when I type it in my terminal.</p></td>
|
||
<td><p>Did you <a class="reference internal" href="#pymanager"><span class="std std-ref">install the Python install manager</span></a>?</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td></td>
|
||
<td><p>Click Start, open “Manage app execution aliases”, and check that the
|
||
aliases for “Python (default)” are enabled.
|
||
If they already are, try disabling and re-enabling to refresh the command.
|
||
The “Python (default windowed)” and “Python install manager” commands
|
||
may also need refreshing.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td></td>
|
||
<td><p>Ensure your <span class="target" id="index-14"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code> variable contains the entry for
|
||
<code class="docutils literal notranslate"><span class="pre">%UserProfile%\AppData\Local\Microsoft\WindowsApps</span></code>.
|
||
The operating system includes this entry once by default, after other
|
||
user paths. If removed, shortcuts will not be found.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">py</span></code> gives me a “can’t open file” error when I type commands in my
|
||
terminal.</p></td>
|
||
<td><p>This usually means you have the legacy launcher installed and
|
||
it has priority over the Python install manager.
|
||
To remove, click Start, open “Installed apps”,
|
||
search for “Python launcher” and uninstall it.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">python</span></code> doesn’t launch the same runtime as <code class="docutils literal notranslate"><span class="pre">py</span></code></p></td>
|
||
<td><p>Click Start, open “Installed apps”, look for any existing Python runtimes,
|
||
and either remove them or Modify and disable the <span class="target" id="index-15"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code> options.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td></td>
|
||
<td><p>Click Start, open “Manage app execution aliases”, and check that your
|
||
<code class="docutils literal notranslate"><span class="pre">python.exe</span></code> alias is set to “Python (default)”</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">python</span></code> and <code class="docutils literal notranslate"><span class="pre">py</span></code> don’t launch the runtime I expect</p></td>
|
||
<td><p>Check your <span class="target" id="index-16"></span><a class="reference internal" href="#envvar-PYTHON_MANAGER_DEFAULT"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHON_MANAGER_DEFAULT</span></code></a> environment variable
|
||
or <code class="docutils literal notranslate"><span class="pre">default_tag</span></code> configuration.
|
||
The <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">list</span></code> command will show your default based on these settings.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td></td>
|
||
<td><p>Installs that are managed by the Python install manager will be chosen
|
||
ahead of unmanaged installs.
|
||
Use <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">install</span></code> to install the runtime you expect,
|
||
or configure your default tag.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td></td>
|
||
<td><p>Prerelease and experimental installs that are not managed by the Python
|
||
install manager may be chosen ahead of stable releases.
|
||
Configure your default tag or uninstall the prerelease runtime
|
||
and reinstall it using <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">install</span></code>.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">pythonw</span></code> or <code class="docutils literal notranslate"><span class="pre">pyw</span></code> don’t launch the same runtime as <code class="docutils literal notranslate"><span class="pre">python</span></code> or <code class="docutils literal notranslate"><span class="pre">py</span></code></p></td>
|
||
<td><p>Click Start, open “Manage app execution aliases”, and check that your
|
||
<code class="docutils literal notranslate"><span class="pre">pythonw.exe</span></code> and <code class="docutils literal notranslate"><span class="pre">pyw.exe</span></code> aliases are consistent with your others.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">pip</span></code> gives me a “command not found” error when I type it in my terminal.</p></td>
|
||
<td><p>Have you activated a virtual environment?
|
||
Run the <code class="docutils literal notranslate"><span class="pre">.venv\Scripts\activate</span></code> script in your terminal to activate.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td></td>
|
||
<td><p>The package may be available but missing the generated executable.
|
||
We recommend using the <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-m</span> <span class="pre">pip</span></code> command instead.
|
||
Running <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">install</span> <span class="pre">--refresh</span></code> and ensuring that the global shortcuts
|
||
directory is on <span class="target" id="index-17"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code> (it will be shown in the command output if
|
||
it is not) should make commands such as <code class="docutils literal notranslate"><span class="pre">pip</span></code> (and other installed
|
||
packages) available.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>I installed a package with <code class="docutils literal notranslate"><span class="pre">pip</span></code> but its command is not found.</p></td>
|
||
<td><p>Have you activated a virtual environment?
|
||
Run the <code class="docutils literal notranslate"><span class="pre">.venv\Scripts\activate</span></code> script in your terminal to activate.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td></td>
|
||
<td><p>New packages do not automatically have global shortcuts created by the
|
||
Python install manager. Similarly, uninstalled packages do not have their
|
||
shortcuts removed.
|
||
Run <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">install</span> <span class="pre">--refresh</span></code> to update the global shortcuts for newly
|
||
installed packages.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>Typing <code class="docutils literal notranslate"><span class="pre">script-name.py</span></code> in the terminal opens in a new window.</p></td>
|
||
<td><p>This is a known limitation of the operating system. Either specify <code class="docutils literal notranslate"><span class="pre">py</span></code>
|
||
before the script name, create a batch file containing <code class="docutils literal notranslate"><span class="pre">@py</span> <span class="pre">"%~dpn0.py"</span> <span class="pre">%*</span></code>
|
||
with the same name as the script, or install the <a class="reference external" href="https://www.python.org/ftp/python/3.14.0/win32/launcher.msi">legacy launcher</a>
|
||
and select it as the association for scripts.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>Drag-dropping files onto a script doesn’t work</p></td>
|
||
<td><p>This is a known limitation of the operating system. It is supported with
|
||
the <a class="reference external" href="https://www.python.org/ftp/python/3.14.0/win32/launcher.msi">legacy launcher</a>, or with the Python install manager when installed
|
||
from the MSI.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>I have installed the Python install manager multiple times.</p></td>
|
||
<td><p>It is possible to install from the Store or WinGet, from the MSIX on
|
||
the Python website, and from the MSI, all at once.
|
||
They are all compatible and will share configuration and runtimes.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td></td>
|
||
<td><p>See the earlier <a class="reference internal" href="#pymanager-advancedinstall"><span class="std std-ref">Advanced installation</span></a> section for ways to
|
||
uninstall the install manager other than the typical Installed Apps
|
||
(Add and Remove Programs) settings page.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>My old <code class="docutils literal notranslate"><span class="pre">py.ini</span></code> settings no longer work.</p></td>
|
||
<td><p>The new Python install manager no longer supports this configuration file
|
||
or its settings, and so it will be ignored.
|
||
See <a class="reference internal" href="#pymanager-config"><span class="std std-ref">Configuration</span></a> for information about configuration settings.</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</section>
|
||
</section>
|
||
<section id="the-embeddable-package">
|
||
<span id="windows-embeddable"></span><h2><span class="section-number">4.2. </span>The embeddable package<a class="headerlink" href="#the-embeddable-package" title="Link to this heading">¶</a></h2>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.5.</span></p>
|
||
</div>
|
||
<p>The embedded distribution is a ZIP file containing a minimal Python environment.
|
||
It is intended for acting as part of another application, rather than being
|
||
directly accessed by end-users.</p>
|
||
<p>To install an embedded distribution, we recommend using <code class="docutils literal notranslate"><span class="pre">py</span> <span class="pre">install</span></code> with the
|
||
<code class="docutils literal notranslate"><span class="pre">--target</span></code> option:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$> py install 3.14-embed --target=<directory>
|
||
</pre></div>
|
||
</div>
|
||
<p>When extracted, the embedded distribution is (almost) fully isolated from the
|
||
user’s system, including environment variables, system registry settings, and
|
||
installed packages. The standard library is included as pre-compiled and
|
||
optimized <code class="docutils literal notranslate"><span class="pre">.pyc</span></code> files in a ZIP, and <code class="docutils literal notranslate"><span class="pre">python3.dll</span></code>, <code class="docutils literal notranslate"><span class="pre">python313.dll</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">python.exe</span></code> and <code class="docutils literal notranslate"><span class="pre">pythonw.exe</span></code> are all provided. Tcl/tk (including all
|
||
dependents, such as Idle), pip and the Python documentation are not included.</p>
|
||
<p>A default <code class="docutils literal notranslate"><span class="pre">._pth</span></code> file is included, which further restricts the default search
|
||
paths (as described below in <a class="reference internal" href="#windows-finding-modules"><span class="std std-ref">Finding modules</span></a>). This file is
|
||
intended for embedders to modify as necessary.</p>
|
||
<p>Third-party packages should be installed by the application installer alongside
|
||
the embedded distribution. Using pip to manage dependencies as for a regular
|
||
Python installation is not supported with this distribution, though with some
|
||
care it may be possible to include and use pip for automatic updates. In
|
||
general, third-party packages should be treated as part of the application
|
||
(“vendoring”) so that the developer can ensure compatibility with newer
|
||
versions before providing updates to users.</p>
|
||
<p>The two recommended use cases for this distribution are described below.</p>
|
||
<section id="python-application">
|
||
<h3><span class="section-number">4.2.1. </span>Python application<a class="headerlink" href="#python-application" title="Link to this heading">¶</a></h3>
|
||
<p>An application written in Python does not necessarily require users to be aware
|
||
of that fact. The embedded distribution may be used in this case to include a
|
||
private version of Python in an install package. Depending on how transparent it
|
||
should be (or conversely, how professional it should appear), there are two
|
||
options.</p>
|
||
<p>Using a specialized executable as a launcher requires some coding, but provides
|
||
the most transparent experience for users. With a customized launcher, there are
|
||
no obvious indications that the program is running on Python: icons can be
|
||
customized, company and version information can be specified, and file
|
||
associations behave properly. In most cases, a custom launcher should simply be
|
||
able to call <code class="docutils literal notranslate"><span class="pre">Py_Main</span></code> with a hard-coded command line.</p>
|
||
<p>The simpler approach is to provide a batch file or generated shortcut that
|
||
directly calls the <code class="docutils literal notranslate"><span class="pre">python.exe</span></code> or <code class="docutils literal notranslate"><span class="pre">pythonw.exe</span></code> with the required
|
||
command-line arguments. In this case, the application will appear to be Python
|
||
and not its actual name, and users may have trouble distinguishing it from other
|
||
running Python processes or file associations.</p>
|
||
<p>With the latter approach, packages should be installed as directories alongside
|
||
the Python executable to ensure they are available on the path. With the
|
||
specialized launcher, packages can be located in other locations as there is an
|
||
opportunity to specify the search path before launching the application.</p>
|
||
</section>
|
||
<section id="embedding-python">
|
||
<h3><span class="section-number">4.2.2. </span>Embedding Python<a class="headerlink" href="#embedding-python" title="Link to this heading">¶</a></h3>
|
||
<p>Applications written in native code often require some form of scripting
|
||
language, and the embedded Python distribution can be used for this purpose. In
|
||
general, the majority of the application is in native code, and some part will
|
||
either invoke <code class="docutils literal notranslate"><span class="pre">python.exe</span></code> or directly use <code class="docutils literal notranslate"><span class="pre">python3.dll</span></code>. For either case,
|
||
extracting the embedded distribution to a subdirectory of the application
|
||
installation is sufficient to provide a loadable Python interpreter.</p>
|
||
<p>As with the application use, packages can be installed to any location as there
|
||
is an opportunity to specify search paths before initializing the interpreter.
|
||
Otherwise, there is no fundamental differences between using the embedded
|
||
distribution and a regular installation.</p>
|
||
</section>
|
||
</section>
|
||
<section id="the-nuget-org-packages">
|
||
<span id="windows-nuget"></span><h2><span class="section-number">4.3. </span>The nuget.org packages<a class="headerlink" href="#the-nuget-org-packages" title="Link to this heading">¶</a></h2>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.5.2.</span></p>
|
||
</div>
|
||
<p>The nuget.org package is a reduced size Python environment intended for use on
|
||
continuous integration and build systems that do not have a system-wide
|
||
install of Python. While nuget is “the package manager for .NET”, it also works
|
||
perfectly fine for packages containing build-time tools.</p>
|
||
<p>Visit <a class="reference external" href="https://www.nuget.org/">nuget.org</a> for the most up-to-date information
|
||
on using nuget. What follows is a summary that is sufficient for Python
|
||
developers.</p>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">nuget.exe</span></code> command line tool may be downloaded directly from
|
||
<code class="docutils literal notranslate"><span class="pre">https://dist.nuget.org/win-x86-commandline/latest/nuget.exe</span></code>, for example,
|
||
using curl or PowerShell. With the tool, the latest version of Python for
|
||
64-bit or 32-bit machines is installed using:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>nuget.exe install python -ExcludeVersion -OutputDirectory .
|
||
nuget.exe install pythonx86 -ExcludeVersion -OutputDirectory .
|
||
</pre></div>
|
||
</div>
|
||
<p>To select a particular version, add a <code class="docutils literal notranslate"><span class="pre">-Version</span> <span class="pre">3.x.y</span></code>. The output directory
|
||
may be changed from <code class="docutils literal notranslate"><span class="pre">.</span></code>, and the package will be installed into a
|
||
subdirectory. By default, the subdirectory is named the same as the package,
|
||
and without the <code class="docutils literal notranslate"><span class="pre">-ExcludeVersion</span></code> option this name will include the specific
|
||
version installed. Inside the subdirectory is a <code class="docutils literal notranslate"><span class="pre">tools</span></code> directory that
|
||
contains the Python installation:</p>
|
||
<div class="highlight-doscon notranslate"><div class="highlight"><pre><span></span><span class="go"># Without -ExcludeVersion</span>
|
||
<span class="gp">></span> .\python.3.5.2\tools\python.exe -V
|
||
<span class="go">Python 3.5.2</span>
|
||
|
||
<span class="go"># With -ExcludeVersion</span>
|
||
<span class="gp">></span> .\python\tools\python.exe -V
|
||
<span class="go">Python 3.5.2</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>In general, nuget packages are not upgradeable, and newer versions should be
|
||
installed side-by-side and referenced using the full path. Alternatively,
|
||
delete the package directory manually and install it again. Many CI systems
|
||
will do this automatically if they do not preserve files between builds.</p>
|
||
<p>Alongside the <code class="docutils literal notranslate"><span class="pre">tools</span></code> directory is a <code class="docutils literal notranslate"><span class="pre">build\native</span></code> directory. This
|
||
contains a MSBuild properties file <code class="docutils literal notranslate"><span class="pre">python.props</span></code> that can be used in a
|
||
C++ project to reference the Python install. Including the settings will
|
||
automatically use the headers and import libraries in your build.</p>
|
||
<p>The package information pages on nuget.org are
|
||
<a class="reference external" href="https://www.nuget.org/packages/python">www.nuget.org/packages/python</a>
|
||
for the 64-bit version, <a class="reference external" href="https://www.nuget.org/packages/pythonx86">www.nuget.org/packages/pythonx86</a> for the 32-bit version, and
|
||
<a class="reference external" href="https://www.nuget.org/packages/pythonarm64">www.nuget.org/packages/pythonarm64</a> for the ARM64 version</p>
|
||
<section id="free-threaded-packages">
|
||
<h3><span class="section-number">4.3.1. </span>Free-threaded packages<a class="headerlink" href="#free-threaded-packages" title="Link to this heading">¶</a></h3>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.13.</span></p>
|
||
</div>
|
||
<p>Packages containing free-threaded binaries are named
|
||
<a class="reference external" href="https://www.nuget.org/packages/python-freethreaded">python-freethreaded</a>
|
||
for the 64-bit version, <a class="reference external" href="https://www.nuget.org/packages/pythonx86-freethreaded">pythonx86-freethreaded</a> for the 32-bit
|
||
version, and <a class="reference external" href="https://www.nuget.org/packages/pythonarm64-freethreaded">pythonarm64-freethreaded</a> for the ARM64
|
||
version. These packages contain both the <code class="docutils literal notranslate"><span class="pre">python3.13t.exe</span></code> and
|
||
<code class="docutils literal notranslate"><span class="pre">python.exe</span></code> entry points, both of which run free threaded.</p>
|
||
</section>
|
||
</section>
|
||
<section id="alternative-bundles">
|
||
<h2><span class="section-number">4.4. </span>Alternative bundles<a class="headerlink" href="#alternative-bundles" title="Link to this heading">¶</a></h2>
|
||
<p>Besides the standard CPython distribution, there are modified packages including
|
||
additional functionality. The following is a list of popular versions and their
|
||
key features:</p>
|
||
<dl>
|
||
<dt><a class="reference external" href="https://www.activestate.com/products/python/">ActivePython</a></dt><dd><p>Installer with multi-platform compatibility, documentation, PyWin32</p>
|
||
</dd>
|
||
<dt><a class="reference external" href="https://www.anaconda.com/download/">Anaconda</a></dt><dd><p>Popular scientific modules (such as numpy, scipy and pandas) and the
|
||
<code class="docutils literal notranslate"><span class="pre">conda</span></code> package manager.</p>
|
||
</dd>
|
||
<dt><a class="reference external" href="https://assets.enthought.com/downloads/edm/">Enthought Deployment Manager</a></dt><dd><p>“The Next Generation Python Environment and Package Manager”.</p>
|
||
<p>Previously Enthought provided Canopy, but it <a class="reference external" href="https://support.enthought.com/hc/en-us/articles/360038600051-Canopy-GUI-end-of-life-transition-to-the-Enthought-Deployment-Manager-EDM-and-Visual-Studio-Code">reached end of life in 2016</a>.</p>
|
||
</dd>
|
||
<dt><a class="reference external" href="https://winpython.github.io/">WinPython</a></dt><dd><p>Windows-specific distribution with prebuilt scientific packages and
|
||
tools for building packages.</p>
|
||
</dd>
|
||
</dl>
|
||
<p>Note that these packages may not include the latest versions of Python or
|
||
other libraries, and are not maintained or supported by the core Python team.</p>
|
||
</section>
|
||
<section id="supported-windows-versions">
|
||
<h2><span class="section-number">4.5. </span>Supported Windows versions<a class="headerlink" href="#supported-windows-versions" title="Link to this heading">¶</a></h2>
|
||
<p>As specified in <span class="target" id="index-18"></span><a class="pep reference external" href="https://peps.python.org/pep-0011/"><strong>PEP 11</strong></a>, a Python release only supports a Windows platform
|
||
while Microsoft considers the platform under extended support. This means that
|
||
Python 3.15 supports Windows 10 and newer. If you require Windows 7
|
||
support, please install Python 3.8. If you require Windows 8.1 support,
|
||
please install Python 3.12.</p>
|
||
</section>
|
||
<section id="removing-the-max-path-limitation">
|
||
<span id="max-path"></span><h2><span class="section-number">4.6. </span>Removing the MAX_PATH limitation<a class="headerlink" href="#removing-the-max-path-limitation" title="Link to this heading">¶</a></h2>
|
||
<p>Windows historically has limited path lengths to 260 characters. This meant that
|
||
paths longer than this would not resolve and errors would result.</p>
|
||
<p>In the latest versions of Windows, this limitation can be expanded to over
|
||
32,000 characters. Your administrator will need to activate the “Enable Win32
|
||
long paths” group policy, or set <code class="docutils literal notranslate"><span class="pre">LongPathsEnabled</span></code> to <code class="docutils literal notranslate"><span class="pre">1</span></code> in the registry
|
||
key <code class="docutils literal notranslate"><span class="pre">HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem</span></code>.</p>
|
||
<p>This allows the <a class="reference internal" href="../builtins/functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> function, the <a class="reference internal" href="../library/os.html#module-os" title="os: Miscellaneous operating system interfaces."><code class="xref py py-mod docutils literal notranslate"><span class="pre">os</span></code></a> module and most other
|
||
path functionality to accept and return paths longer than 260 characters.</p>
|
||
<p>After changing the above option and rebooting, no further configuration is
|
||
required.</p>
|
||
</section>
|
||
<section id="utf-8-mode">
|
||
<span id="win-utf8-mode"></span><h2><span class="section-number">4.7. </span>UTF-8 mode<a class="headerlink" href="#utf-8-mode" title="Link to this heading">¶</a></h2>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.7.</span></p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.15: </span>Python UTF-8 mode is now enabled by default (<span class="target" id="index-19"></span><a class="pep reference external" href="https://peps.python.org/pep-0686/"><strong>PEP 686</strong></a>).</p>
|
||
</div>
|
||
<p>Windows still uses legacy encodings for the system encoding (the ANSI Code
|
||
Page). When the <a class="reference internal" href="../library/os.html#utf8-mode"><span class="std std-ref">Python UTF-8 Mode</span></a> is disabled, Python
|
||
uses the ANSI Code Page as the default encoding of text files, as
|
||
returned by <a class="reference internal" href="../library/locale.html#locale.getencoding" title="locale.getencoding"><code class="xref py py-func docutils literal notranslate"><span class="pre">locale.getencoding()</span></code></a>.</p>
|
||
<p>This may cause issues because UTF-8 is widely used on the internet
|
||
and most Unix systems, including WSL (Windows Subsystem for Linux).</p>
|
||
<p>The <a class="reference internal" href="../library/os.html#utf8-mode"><span class="std std-ref">Python UTF-8 Mode</span></a>, enabled by default, ignores the
|
||
system encoding and uses UTF-8 as the default text encoding.
|
||
When the <a class="reference internal" href="../library/os.html#utf8-mode"><span class="std std-ref">UTF-8 mode</span></a> is enabled, you can still use the
|
||
system encoding (the ANSI Code Page) via the “mbcs” codec.</p>
|
||
<p>You can disable the <a class="reference internal" href="../library/os.html#utf8-mode"><span class="std std-ref">Python UTF-8 Mode</span></a> via
|
||
the <code class="docutils literal notranslate"><span class="pre">-X</span> <span class="pre">utf8=0</span></code> command line option, or the <code class="docutils literal notranslate"><span class="pre">PYTHONUTF8=0</span></code> environment
|
||
variable. See <span class="target" id="index-20"></span><a class="reference internal" href="cmdline.html#envvar-PYTHONUTF8"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONUTF8</span></code></a> for disabling UTF-8 mode, and
|
||
<a class="reference internal" href="#setting-envvars"><span class="std std-ref">Python install manager</span></a> for how to modify environment variables.</p>
|
||
<div class="admonition hint">
|
||
<p class="admonition-title">Hint</p>
|
||
<p>Adding <code class="docutils literal notranslate"><span class="pre">PYTHONUTF8={0,1}</span></code> to the default environment variables
|
||
will affect all Python 3.7+ applications on your system.
|
||
If you have any Python 3.7+ applications which rely on the legacy
|
||
system encoding, it is recommended to set the environment variable
|
||
temporarily or use the <code class="docutils literal notranslate"><span class="pre">-X</span> <span class="pre">utf8</span></code> command line option.</p>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Even when UTF-8 mode is disabled, Python uses UTF-8 by default
|
||
on Windows for:</p>
|
||
<ul class="simple">
|
||
<li><p>Console I/O including standard I/O (see <span class="target" id="index-21"></span><a class="pep reference external" href="https://peps.python.org/pep-0528/"><strong>PEP 528</strong></a> for details).</p></li>
|
||
<li><p>The <a class="reference internal" href="../glossary.html#term-filesystem-encoding-and-error-handler"><span class="xref std std-term">filesystem encoding</span></a>
|
||
(see <span class="target" id="index-22"></span><a class="pep reference external" href="https://peps.python.org/pep-0529/"><strong>PEP 529</strong></a> for details).</p></li>
|
||
</ul>
|
||
</div>
|
||
</section>
|
||
<section id="finding-modules">
|
||
<span id="windows-finding-modules"></span><h2><span class="section-number">4.8. </span>Finding modules<a class="headerlink" href="#finding-modules" title="Link to this heading">¶</a></h2>
|
||
<p>These notes supplement the description at <a class="reference internal" href="../library/sys_path_init.html#sys-path-init"><span class="std std-ref">The initialization of the sys.path module search path</span></a> with
|
||
detailed Windows notes.</p>
|
||
<p>When no <code class="docutils literal notranslate"><span class="pre">._pth</span></code> file is found, this is how <a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a> is populated on
|
||
Windows:</p>
|
||
<ul class="simple">
|
||
<li><p>An empty entry is added at the start, which corresponds to the current
|
||
directory.</p></li>
|
||
<li><p>If the environment variable <span class="target" id="index-23"></span><a class="reference internal" href="cmdline.html#envvar-PYTHONPATH"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONPATH</span></code></a> exists, as described in
|
||
<a class="reference internal" href="cmdline.html#using-on-envvars"><span class="std std-ref">Environment variables</span></a>, its entries are added next. Note that on Windows,
|
||
paths in this variable must be separated by semicolons, to distinguish them
|
||
from the colon used in drive identifiers (<code class="docutils literal notranslate"><span class="pre">C:\</span></code> etc.).</p></li>
|
||
<li><p>Additional “application paths” can be added in the registry as subkeys of
|
||
<code class="samp docutils literal notranslate"><span class="pre">\SOFTWARE\Python\PythonCore{version}\PythonPath</span></code> under both the
|
||
<code class="docutils literal notranslate"><span class="pre">HKEY_CURRENT_USER</span></code> and <code class="docutils literal notranslate"><span class="pre">HKEY_LOCAL_MACHINE</span></code> hives. Subkeys which have
|
||
semicolon-delimited path strings as their default value will cause each path
|
||
to be added to <a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a>. (Note that all known installers only use
|
||
HKLM, so HKCU is typically empty.)</p></li>
|
||
<li><p>If the environment variable <span class="target" id="index-24"></span><a class="reference internal" href="cmdline.html#envvar-PYTHONHOME"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONHOME</span></code></a> is set, it is assumed as
|
||
“Python Home”. Otherwise, the path of the main Python executable is used to
|
||
locate a “landmark file” (either <code class="docutils literal notranslate"><span class="pre">Lib\os.py</span></code> or <code class="docutils literal notranslate"><span class="pre">pythonXY.zip</span></code>) to deduce
|
||
the “Python Home”. If a Python home is found, the relevant sub-directories
|
||
added to <a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a> (<code class="docutils literal notranslate"><span class="pre">Lib</span></code>, <code class="docutils literal notranslate"><span class="pre">plat-win</span></code>, etc) are based on that
|
||
folder. Otherwise, the core Python path is constructed from the PythonPath
|
||
stored in the registry.</p></li>
|
||
<li><p>If the Python Home cannot be located, no <span class="target" id="index-25"></span><a class="reference internal" href="cmdline.html#envvar-PYTHONPATH"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONPATH</span></code></a> is specified in
|
||
the environment, and no registry entries can be found, a default path with
|
||
relative entries is used (e.g. <code class="docutils literal notranslate"><span class="pre">.\Lib;.\plat-win</span></code>, etc).</p></li>
|
||
</ul>
|
||
<p>If a <code class="docutils literal notranslate"><span class="pre">pyvenv.cfg</span></code> file is found alongside the main executable or in the
|
||
directory one level above the executable, the following variations apply:</p>
|
||
<ul class="simple">
|
||
<li><p>If <code class="docutils literal notranslate"><span class="pre">home</span></code> is an absolute path and <span class="target" id="index-26"></span><a class="reference internal" href="cmdline.html#envvar-PYTHONHOME"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONHOME</span></code></a> is not set, this
|
||
path is used instead of the path to the main executable when deducing the
|
||
home location.</p></li>
|
||
</ul>
|
||
<p>The end result of all this is:</p>
|
||
<ul class="simple">
|
||
<li><p>When running <code class="file docutils literal notranslate"><span class="pre">python.exe</span></code>, or any other .exe in the main Python
|
||
directory (either an installed version, or directly from the PCbuild
|
||
directory), the core path is deduced, and the core paths in the registry are
|
||
ignored. Other “application paths” in the registry are always read.</p></li>
|
||
<li><p>When Python is hosted in another .exe (different directory, embedded via COM,
|
||
etc), the “Python Home” will not be deduced, so the core path from the
|
||
registry is used. Other “application paths” in the registry are always read.</p></li>
|
||
<li><p>If Python can’t find its home and there are no registry value (frozen .exe,
|
||
some very strange installation setup) you get a path with some default, but
|
||
relative, paths.</p></li>
|
||
</ul>
|
||
<p>For those who want to bundle Python into their application or distribution, the
|
||
following advice will prevent conflicts with other installations:</p>
|
||
<ul class="simple">
|
||
<li><p>Include a <code class="docutils literal notranslate"><span class="pre">._pth</span></code> file alongside your executable containing the
|
||
directories to include. This will ignore paths listed in the registry and
|
||
environment variables, and also ignore <a class="reference internal" href="../library/site.html#module-site" title="site: Module responsible for site-specific configuration."><code class="xref py py-mod docutils literal notranslate"><span class="pre">site</span></code></a> unless <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">site</span></code> is
|
||
listed.</p></li>
|
||
<li><p>If you are loading <code class="file docutils literal notranslate"><span class="pre">python3.dll</span></code> or <code class="file docutils literal notranslate"><span class="pre">python37.dll</span></code> in your own
|
||
executable, explicitly set <a class="reference internal" href="../c-api/init_config.html#c.PyConfig.module_search_paths" title="PyConfig.module_search_paths"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.module_search_paths</span></code></a> before
|
||
<a class="reference internal" href="../c-api/interp-lifecycle.html#c.Py_InitializeFromConfig" title="Py_InitializeFromConfig"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_InitializeFromConfig()</span></code></a>.</p></li>
|
||
<li><p>Clear and/or overwrite <span class="target" id="index-27"></span><a class="reference internal" href="cmdline.html#envvar-PYTHONPATH"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONPATH</span></code></a> and set <span class="target" id="index-28"></span><a class="reference internal" href="cmdline.html#envvar-PYTHONHOME"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONHOME</span></code></a>
|
||
before launching <code class="file docutils literal notranslate"><span class="pre">python.exe</span></code> from your application.</p></li>
|
||
<li><p>If you cannot use the previous suggestions (for example, you are a
|
||
distribution that allows people to run <code class="file docutils literal notranslate"><span class="pre">python.exe</span></code> directly), ensure
|
||
that the landmark file (<code class="file docutils literal notranslate"><span class="pre">Lib\os.py</span></code>) exists in your install directory.
|
||
(Note that it will not be detected inside a ZIP file, but a correctly named
|
||
ZIP file will be detected instead.)</p></li>
|
||
</ul>
|
||
<p>These will ensure that the files in a system-wide installation will not take
|
||
precedence over the copy of the standard library bundled with your application.
|
||
Otherwise, your users may experience problems using your application. Note that
|
||
the first suggestion is the best, as the others may still be susceptible to
|
||
non-standard paths in the registry and user site-packages.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Add <code class="docutils literal notranslate"><span class="pre">._pth</span></code> file support and removes <code class="docutils literal notranslate"><span class="pre">applocal</span></code> option from
|
||
<code class="docutils literal notranslate"><span class="pre">pyvenv.cfg</span></code>.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Add <code class="file docutils literal notranslate"><span class="pre">python</span><em><span class="pre">XX</span></em><span class="pre">.zip</span></code> as a potential landmark when directly adjacent
|
||
to the executable.</p>
|
||
</div>
|
||
<div class="deprecated">
|
||
<p><span class="versionmodified deprecated">Deprecated since version 3.6: </span>Modules specified in the registry under <code class="docutils literal notranslate"><span class="pre">Modules</span></code> (not <code class="docutils literal notranslate"><span class="pre">PythonPath</span></code>)
|
||
may be imported by <a class="reference internal" href="../library/importlib.html#importlib.machinery.WindowsRegistryFinder" title="importlib.machinery.WindowsRegistryFinder"><code class="xref py py-class docutils literal notranslate"><span class="pre">importlib.machinery.WindowsRegistryFinder</span></code></a>.
|
||
This finder is enabled on Windows in 3.6.0 and earlier, but may need to
|
||
be explicitly added to <a class="reference internal" href="../library/sys.html#sys.meta_path" title="sys.meta_path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.meta_path</span></code></a> in the future.</p>
|
||
</div>
|
||
</section>
|
||
<section id="additional-modules">
|
||
<h2><span class="section-number">4.9. </span>Additional modules<a class="headerlink" href="#additional-modules" title="Link to this heading">¶</a></h2>
|
||
<p>Even though Python aims to be portable among all platforms, there are features
|
||
that are unique to Windows. A couple of modules, both in the standard library
|
||
and external, and snippets exist to use these features.</p>
|
||
<p>The Windows-specific standard modules are documented in
|
||
<a class="reference internal" href="../library/windows.html#mswin-specific-services"><span class="std std-ref">MS Windows Specific Services</span></a>.</p>
|
||
<section id="pywin32">
|
||
<h3><span class="section-number">4.9.1. </span>PyWin32<a class="headerlink" href="#pywin32" title="Link to this heading">¶</a></h3>
|
||
<p>The <a class="extlink-pypi reference external" href="https://pypi.org/project/PyWin32/">PyWin32</a> module by Mark Hammond
|
||
is a collection of modules for advanced Windows-specific support. This includes
|
||
utilities for:</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference external" href="https://learn.microsoft.com/windows/win32/com/component-object-model--com--portal">Component Object Model</a>
|
||
(COM)</p></li>
|
||
<li><p>Win32 API calls</p></li>
|
||
<li><p>Registry</p></li>
|
||
<li><p>Event log</p></li>
|
||
<li><p><a class="reference external" href="https://learn.microsoft.com/cpp/mfc/mfc-desktop-applications">Microsoft Foundation Classes</a>
|
||
(MFC) user interfaces</p></li>
|
||
</ul>
|
||
<p><a class="reference external" href="https://web.archive.org/web/20060524042422/https://www.python.org/windows/pythonwin/">PythonWin</a> is a sample MFC application
|
||
shipped with PyWin32. It is an embeddable IDE with a built-in debugger.</p>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<dl class="simple">
|
||
<dt><a class="reference external" href="https://timgolden.me.uk/python/win32_how_do_i.html">Win32 How Do I…?</a></dt><dd><p>by Tim Golden</p>
|
||
</dd>
|
||
<dt><a class="reference external" href="https://www.boddie.org.uk/python/COM.html">Python and COM</a></dt><dd><p>by David and Paul Boddie</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
</section>
|
||
<section id="cx-freeze">
|
||
<h3><span class="section-number">4.9.2. </span>cx_Freeze<a class="headerlink" href="#cx-freeze" title="Link to this heading">¶</a></h3>
|
||
<p><a class="reference external" href="https://cx-freeze.readthedocs.io/en/latest/">cx_Freeze</a>
|
||
wraps Python scripts into executable Windows programs
|
||
(<code class="file docutils literal notranslate"><em><span class="pre">*</span></em><span class="pre">.exe</span></code> files). When you have done this, you can distribute your
|
||
application without requiring your users to install Python.</p>
|
||
</section>
|
||
</section>
|
||
<section id="compiling-python-on-windows">
|
||
<h2><span class="section-number">4.10. </span>Compiling Python on Windows<a class="headerlink" href="#compiling-python-on-windows" title="Link to this heading">¶</a></h2>
|
||
<p>If you want to compile CPython yourself, first thing you should do is get the
|
||
<a class="reference external" href="https://www.python.org/downloads/source/">source</a>. You can download either the
|
||
latest release’s source or just grab a fresh <a class="reference external" href="https://devguide.python.org/setup/#get-the-source-code">checkout</a>.</p>
|
||
<p>The source tree contains a build solution and project files for Microsoft
|
||
Visual Studio, which is the compiler used to build the official Python
|
||
releases. These files are in the <code class="file docutils literal notranslate"><span class="pre">PCbuild</span></code> directory.</p>
|
||
<p>Check <code class="file docutils literal notranslate"><span class="pre">PCbuild/readme.txt</span></code> for general information on the build process.</p>
|
||
<p>For extension modules, consult <a class="reference internal" href="../extending/windows.html#building-on-windows"><span class="std std-ref">Building C and C++ Extensions on Windows</span></a>.</p>
|
||
</section>
|
||
<section id="the-full-installer-deprecated">
|
||
<span id="windows-full"></span><h2><span class="section-number">4.11. </span>The full installer (deprecated)<a class="headerlink" href="#the-full-installer-deprecated" title="Link to this heading">¶</a></h2>
|
||
<div class="deprecated">
|
||
<p><span class="versionmodified deprecated">Deprecated since version 3.14: </span>This installer is deprecated since 3.14 and will not be produced for Python
|
||
3.16 or later. See <a class="reference internal" href="#pymanager"><span class="std std-ref">Python install manager</span></a> for the modern installer.</p>
|
||
</div>
|
||
<section id="installation-steps">
|
||
<h3><span class="section-number">4.11.1. </span>Installation steps<a class="headerlink" href="#installation-steps" title="Link to this heading">¶</a></h3>
|
||
<p>Four Python 3.15 installers are available for download - two each for the
|
||
32-bit and 64-bit versions of the interpreter. The <em>web installer</em> is a small
|
||
initial download, and it will automatically download the required components as
|
||
necessary. The <em>offline installer</em> includes the components necessary for a
|
||
default installation and only requires an internet connection for optional
|
||
features. See <a class="reference internal" href="#install-layout-option"><span class="std std-ref">Installing without downloading</span></a> for other ways to avoid downloading
|
||
during installation.</p>
|
||
<p>After starting the installer, one of two options may be selected:</p>
|
||
<img alt="../_images/win_installer.png" src="../_images/win_installer.png" />
|
||
<p>If you select “Install Now”:</p>
|
||
<ul class="simple">
|
||
<li><p>You will <em>not</em> need to be an administrator (unless a system update for the
|
||
C Runtime Library is required or you install the <a class="reference internal" href="#launcher"><span class="std std-ref">Python install manager</span></a> for all
|
||
users)</p></li>
|
||
<li><p>Python will be installed into your user directory</p></li>
|
||
<li><p>The <a class="reference internal" href="#launcher"><span class="std std-ref">Python install manager</span></a> will be installed according to the option at the bottom
|
||
of the first page</p></li>
|
||
<li><p>The standard library, test suite, launcher and pip will be installed</p></li>
|
||
<li><p>If selected, the install directory will be added to your <span class="target" id="index-29"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code></p></li>
|
||
<li><p>Shortcuts will only be visible for the current user</p></li>
|
||
</ul>
|
||
<p>Selecting “Customize installation” will allow you to select the features to
|
||
install, the installation location and other options or post-install actions.
|
||
To install debugging symbols or binaries, you will need to use this option.</p>
|
||
<p>To perform an all-users installation, you should select “Customize
|
||
installation”. In this case:</p>
|
||
<ul class="simple">
|
||
<li><p>You may be required to provide administrative credentials or approval</p></li>
|
||
<li><p>Python will be installed into the Program Files directory</p></li>
|
||
<li><p>The <a class="reference internal" href="#launcher"><span class="std std-ref">Python install manager</span></a> will be installed into the Windows directory</p></li>
|
||
<li><p>Optional features may be selected during installation</p></li>
|
||
<li><p>The standard library can be pre-compiled to bytecode</p></li>
|
||
<li><p>If selected, the install directory will be added to the system <span class="target" id="index-30"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code></p></li>
|
||
<li><p>Shortcuts are available for all users</p></li>
|
||
</ul>
|
||
</section>
|
||
<section id="id2">
|
||
<h3><span class="section-number">4.11.2. </span>Removing the MAX_PATH limitation<a class="headerlink" href="#id2" title="Link to this heading">¶</a></h3>
|
||
<p>Windows historically has limited path lengths to 260 characters. This meant that
|
||
paths longer than this would not resolve and errors would result.</p>
|
||
<p>In the latest versions of Windows, this limitation can be expanded to
|
||
approximately 32,000 characters. Your administrator will need to activate the
|
||
“Enable Win32 long paths” group policy, or set <code class="docutils literal notranslate"><span class="pre">LongPathsEnabled</span></code> to <code class="docutils literal notranslate"><span class="pre">1</span></code>
|
||
in the registry key
|
||
<code class="docutils literal notranslate"><span class="pre">HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem</span></code>.</p>
|
||
<p>This allows the <a class="reference internal" href="../builtins/functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> function, the <a class="reference internal" href="../library/os.html#module-os" title="os: Miscellaneous operating system interfaces."><code class="xref py py-mod docutils literal notranslate"><span class="pre">os</span></code></a> module and most other
|
||
path functionality to accept and return paths longer than 260 characters.</p>
|
||
<p>After changing the above option, no further configuration is required.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Support for long paths was enabled in Python.</p>
|
||
</div>
|
||
</section>
|
||
<section id="installing-without-ui">
|
||
<span id="install-quiet-option"></span><h3><span class="section-number">4.11.3. </span>Installing without UI<a class="headerlink" href="#installing-without-ui" title="Link to this heading">¶</a></h3>
|
||
<p>All of the options available in the installer UI can also be specified from the
|
||
command line, allowing scripted installers to replicate an installation on many
|
||
machines without user interaction. These options may also be set without
|
||
suppressing the UI in order to change some of the defaults.</p>
|
||
<p>The following options (found by executing the installer with <code class="docutils literal notranslate"><span class="pre">/?</span></code>) can be
|
||
passed into the installer:</p>
|
||
<table class="docutils align-default">
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>Name</p></th>
|
||
<th class="head"><p>Description</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p>/passive</p></td>
|
||
<td><p>to display progress without requiring user interaction</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>/quiet</p></td>
|
||
<td><p>to install/uninstall without displaying any UI</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>/simple</p></td>
|
||
<td><p>to prevent user customization</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>/uninstall</p></td>
|
||
<td><p>to remove Python (without confirmation)</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>/layout [directory]</p></td>
|
||
<td><p>to pre-download all components</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>/log [filename]</p></td>
|
||
<td><p>to specify log files location</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>All other options are passed as <code class="docutils literal notranslate"><span class="pre">name=value</span></code>, where the value is usually
|
||
<code class="docutils literal notranslate"><span class="pre">0</span></code> to disable a feature, <code class="docutils literal notranslate"><span class="pre">1</span></code> to enable a feature, or a path. The full list
|
||
of available options is shown below.</p>
|
||
<table class="docutils align-default">
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>Name</p></th>
|
||
<th class="head"><p>Description</p></th>
|
||
<th class="head"><p>Default</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p>InstallAllUsers</p></td>
|
||
<td><p>Perform a system-wide installation.</p></td>
|
||
<td><p>0</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>TargetDir</p></td>
|
||
<td><p>The installation directory</p></td>
|
||
<td><p>Selected based on
|
||
InstallAllUsers</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>DefaultAllUsersTargetDir</p></td>
|
||
<td><p>The default installation directory
|
||
for all-user installs</p></td>
|
||
<td><p><code class="file docutils literal notranslate"><span class="pre">%ProgramFiles%\Python</span> <span class="pre">X.Y</span></code> or <code class="file docutils literal notranslate"><span class="pre">%ProgramFiles(x86)%\Python</span> <span class="pre">X.Y</span></code></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>DefaultJustForMeTargetDir</p></td>
|
||
<td><p>The default install directory for
|
||
just-for-me installs</p></td>
|
||
<td><p><code class="file docutils literal notranslate"><span class="pre">%LocalAppData%\Programs\Python\PythonXY</span></code> or
|
||
<code class="file docutils literal notranslate"><span class="pre">%LocalAppData%\Programs\Python\PythonXY-32</span></code> or
|
||
<code class="file docutils literal notranslate"><span class="pre">%LocalAppData%\Programs\Python\PythonXY-64</span></code></p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>DefaultCustomTargetDir</p></td>
|
||
<td><p>The default custom install directory
|
||
displayed in the UI</p></td>
|
||
<td><p>(empty)</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>AssociateFiles</p></td>
|
||
<td><p>Create file associations if the
|
||
launcher is also installed.</p></td>
|
||
<td><p>1</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>CompileAll</p></td>
|
||
<td><p>Compile all <code class="docutils literal notranslate"><span class="pre">.py</span></code> files to
|
||
<code class="docutils literal notranslate"><span class="pre">.pyc</span></code>.</p></td>
|
||
<td><p>0</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>PrependPath</p></td>
|
||
<td><p>Prepend install and Scripts
|
||
directories to <span class="target" id="index-31"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code> and
|
||
add <code class="docutils literal notranslate"><span class="pre">.PY</span></code> to <span class="target" id="index-32"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATHEXT</span></code></p></td>
|
||
<td><p>0</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>AppendPath</p></td>
|
||
<td><p>Append install and Scripts
|
||
directories to <span class="target" id="index-33"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code> and
|
||
add <code class="docutils literal notranslate"><span class="pre">.PY</span></code> to <span class="target" id="index-34"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATHEXT</span></code></p></td>
|
||
<td><p>0</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>Shortcuts</p></td>
|
||
<td><p>Create shortcuts for the interpreter,
|
||
documentation and IDLE if installed.</p></td>
|
||
<td><p>1</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>Include_doc</p></td>
|
||
<td><p>Install Python manual</p></td>
|
||
<td><p>1</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>Include_debug</p></td>
|
||
<td><p>Install debug binaries</p></td>
|
||
<td><p>0</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>Include_dev</p></td>
|
||
<td><p>Install developer headers and
|
||
libraries. Omitting this may lead to
|
||
an unusable installation.</p></td>
|
||
<td><p>1</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>Include_exe</p></td>
|
||
<td><p>Install <code class="file docutils literal notranslate"><span class="pre">python.exe</span></code> and
|
||
related files. Omitting this may
|
||
lead to an unusable installation.</p></td>
|
||
<td><p>1</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>Include_launcher</p></td>
|
||
<td><p>Install <a class="reference internal" href="#launcher"><span class="std std-ref">Python install manager</span></a>.</p></td>
|
||
<td><p>1</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>InstallLauncherAllUsers</p></td>
|
||
<td><p>Installs the launcher for all
|
||
users. Also requires
|
||
<code class="docutils literal notranslate"><span class="pre">Include_launcher</span></code> to be set to 1</p></td>
|
||
<td><p>1</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>Include_lib</p></td>
|
||
<td><p>Install standard library and
|
||
extension modules. Omitting this may
|
||
lead to an unusable installation.</p></td>
|
||
<td><p>1</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>Include_pip</p></td>
|
||
<td><p>Install bundled pip and setuptools</p></td>
|
||
<td><p>1</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>Include_symbols</p></td>
|
||
<td><p>Install debugging symbols (<code class="docutils literal notranslate"><span class="pre">*.pdb</span></code>)</p></td>
|
||
<td><p>0</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>Include_tcltk</p></td>
|
||
<td><p>Install Tcl/Tk support and IDLE</p></td>
|
||
<td><p>1</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>Include_test</p></td>
|
||
<td><p>Install standard library test suite</p></td>
|
||
<td><p>1</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>Include_tools</p></td>
|
||
<td><p>Install utility scripts</p></td>
|
||
<td><p>1</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>LauncherOnly</p></td>
|
||
<td><p>Only installs the launcher. This
|
||
will override most other options.</p></td>
|
||
<td><p>0</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>SimpleInstall</p></td>
|
||
<td><p>Disable most install UI</p></td>
|
||
<td><p>0</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>SimpleInstallDescription</p></td>
|
||
<td><p>A custom message to display when the
|
||
simplified install UI is used.</p></td>
|
||
<td><p>(empty)</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>For example, to silently install a default, system-wide Python installation,
|
||
you could use the following command (from an elevated command prompt):</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>python-3.9.0.exe /quiet InstallAllUsers=1 PrependPath=1 Include_test=0
|
||
</pre></div>
|
||
</div>
|
||
<p>To allow users to easily install a personal copy of Python without the test
|
||
suite, you could provide a shortcut with the following command. This will
|
||
display a simplified initial page and disallow customization:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>python-3.9.0.exe InstallAllUsers=0 Include_launcher=0 Include_test=0
|
||
SimpleInstall=1 SimpleInstallDescription="Just for me, no test suite."
|
||
</pre></div>
|
||
</div>
|
||
<p>(Note that omitting the launcher also omits file associations, and is only
|
||
recommended for per-user installs when there is also a system-wide installation
|
||
that included the launcher.)</p>
|
||
<p>The options listed above can also be provided in a file named <code class="docutils literal notranslate"><span class="pre">unattend.xml</span></code>
|
||
alongside the executable. This file specifies a list of options and values.
|
||
When a value is provided as an attribute, it will be converted to a number if
|
||
possible. Values provided as element text are always left as strings. This
|
||
example file sets the same options as the previous example:</p>
|
||
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><Options></span>
|
||
<span class="w"> </span><span class="nt"><Option</span><span class="w"> </span><span class="na">Name=</span><span class="s">"InstallAllUsers"</span><span class="w"> </span><span class="na">Value=</span><span class="s">"no"</span><span class="w"> </span><span class="nt">/></span>
|
||
<span class="w"> </span><span class="nt"><Option</span><span class="w"> </span><span class="na">Name=</span><span class="s">"Include_launcher"</span><span class="w"> </span><span class="na">Value=</span><span class="s">"0"</span><span class="w"> </span><span class="nt">/></span>
|
||
<span class="w"> </span><span class="nt"><Option</span><span class="w"> </span><span class="na">Name=</span><span class="s">"Include_test"</span><span class="w"> </span><span class="na">Value=</span><span class="s">"no"</span><span class="w"> </span><span class="nt">/></span>
|
||
<span class="w"> </span><span class="nt"><Option</span><span class="w"> </span><span class="na">Name=</span><span class="s">"SimpleInstall"</span><span class="w"> </span><span class="na">Value=</span><span class="s">"yes"</span><span class="w"> </span><span class="nt">/></span>
|
||
<span class="w"> </span><span class="nt"><Option</span><span class="w"> </span><span class="na">Name=</span><span class="s">"SimpleInstallDescription"</span><span class="nt">></span>Just<span class="w"> </span>for<span class="w"> </span>me,<span class="w"> </span>no<span class="w"> </span>test<span class="w"> </span>suite<span class="nt"></Option></span>
|
||
<span class="nt"></Options></span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="installing-without-downloading">
|
||
<span id="install-layout-option"></span><h3><span class="section-number">4.11.4. </span>Installing without downloading<a class="headerlink" href="#installing-without-downloading" title="Link to this heading">¶</a></h3>
|
||
<p>As some features of Python are not included in the initial installer download,
|
||
selecting those features may require an internet connection. To avoid this
|
||
need, all possible components may be downloaded on-demand to create a complete
|
||
<em>layout</em> that will no longer require an internet connection regardless of the
|
||
selected features. Note that this download may be bigger than required, but
|
||
where a large number of installations are going to be performed it is very
|
||
useful to have a locally cached copy.</p>
|
||
<p>Execute the following command from Command Prompt to download all possible
|
||
required files. Remember to substitute <code class="docutils literal notranslate"><span class="pre">python-3.9.0.exe</span></code> for the actual
|
||
name of your installer, and to create layouts in their own directories to
|
||
avoid collisions between files with the same name.</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>python-3.9.0.exe /layout [optional target directory]
|
||
</pre></div>
|
||
</div>
|
||
<p>You may also specify the <code class="docutils literal notranslate"><span class="pre">/quiet</span></code> option to hide the progress display.</p>
|
||
</section>
|
||
<section id="modifying-an-install">
|
||
<h3><span class="section-number">4.11.5. </span>Modifying an install<a class="headerlink" href="#modifying-an-install" title="Link to this heading">¶</a></h3>
|
||
<p>Once Python has been installed, you can add or remove features through the
|
||
Programs and Features tool that is part of Windows. Select the Python entry and
|
||
choose “Uninstall/Change” to open the installer in maintenance mode.</p>
|
||
<p>“Modify” allows you to add or remove features by modifying the checkboxes -
|
||
unchanged checkboxes will not install or remove anything. Some options cannot be
|
||
changed in this mode, such as the install directory; to modify these, you will
|
||
need to remove and then reinstall Python completely.</p>
|
||
<p>“Repair” will verify all the files that should be installed using the current
|
||
settings and replace any that have been removed or modified.</p>
|
||
<p>“Uninstall” will remove Python entirely, with the exception of the
|
||
<a class="reference internal" href="#launcher"><span class="std std-ref">Python install manager</span></a>, which has its own entry in Programs and Features.</p>
|
||
</section>
|
||
<section id="id3">
|
||
<h3><span class="section-number">4.11.6. </span>Installing free-threaded binaries<a class="headerlink" href="#id3" title="Link to this heading">¶</a></h3>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.13.</span></p>
|
||
</div>
|
||
<p>To install pre-built binaries with free-threading enabled (see <span class="target" id="index-35"></span><a class="pep reference external" href="https://peps.python.org/pep-0703/"><strong>PEP 703</strong></a>), you
|
||
should select “Customize installation”. The second page of options includes the
|
||
“Download free-threaded binaries” checkbox.</p>
|
||
<img alt="../_images/win_install_freethreaded.png" src="../_images/win_install_freethreaded.png" />
|
||
<p>Selecting this option will download and install additional binaries to the same
|
||
location as the main Python install. The main executable is called
|
||
<code class="docutils literal notranslate"><span class="pre">python3.13t.exe</span></code>, and other binaries either receive a <code class="docutils literal notranslate"><span class="pre">t</span></code> suffix or a full
|
||
ABI suffix. Python source files and bundled third-party dependencies are shared
|
||
with the main install.</p>
|
||
<p>The free-threaded version is registered as a regular Python install with the
|
||
tag <code class="docutils literal notranslate"><span class="pre">3.13t</span></code> (with a <code class="docutils literal notranslate"><span class="pre">-32</span></code> or <code class="docutils literal notranslate"><span class="pre">-arm64</span></code> suffix as normal for those
|
||
platforms). This allows tools to discover it, and for the <a class="reference internal" href="#launcher"><span class="std std-ref">Python install manager</span></a> to
|
||
support <code class="docutils literal notranslate"><span class="pre">py.exe</span> <span class="pre">-3.13t</span></code>. Note that the launcher will interpret <code class="docutils literal notranslate"><span class="pre">py.exe</span> <span class="pre">-3</span></code>
|
||
(or a <code class="docutils literal notranslate"><span class="pre">python3</span></code> shebang) as “the latest 3.x install”, which will prefer the
|
||
free-threaded binaries over the regular ones, while <code class="docutils literal notranslate"><span class="pre">py.exe</span> <span class="pre">-3.13</span></code> will not.
|
||
If you use the short style of option, you may prefer to not install the
|
||
free-threaded binaries at this time.</p>
|
||
<p>To specify the install option at the command line, use
|
||
<code class="docutils literal notranslate"><span class="pre">Include_freethreaded=1</span></code>. See <a class="reference internal" href="#install-layout-option"><span class="std std-ref">Installing without downloading</span></a> for instructions on
|
||
pre-emptively downloading the additional binaries for offline install. The
|
||
options to include debug symbols and binaries also apply to the free-threaded
|
||
builds.</p>
|
||
<p>Free-threaded binaries are also available <a class="reference internal" href="#windows-nuget"><span class="std std-ref">on nuget.org</span></a>.</p>
|
||
</section>
|
||
</section>
|
||
<section id="python-launcher-for-windows-deprecated">
|
||
<h2><span class="section-number">4.12. </span>Python launcher for Windows (deprecated)<a class="headerlink" href="#python-launcher-for-windows-deprecated" title="Link to this heading">¶</a></h2>
|
||
<div class="deprecated">
|
||
<p><span class="versionmodified deprecated">Deprecated since version 3.14: </span>The launcher and this documentation have been superseded by the Python
|
||
Install Manager described above. This is preserved temporarily for historical
|
||
interest.</p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.3.</span></p>
|
||
</div>
|
||
<p>The Python launcher for Windows is a utility which aids in locating and
|
||
executing of different Python versions. It allows scripts (or the
|
||
command-line) to indicate a preference for a specific Python version, and
|
||
will locate and execute that version.</p>
|
||
<p>Unlike the <span class="target" id="index-36"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code> variable, the launcher will correctly select the most
|
||
appropriate version of Python. It will prefer per-user installations over
|
||
system-wide ones, and orders by language version rather than using the most
|
||
recently installed version.</p>
|
||
<p>The launcher was originally specified in <span class="target" id="index-37"></span><a class="pep reference external" href="https://peps.python.org/pep-0397/"><strong>PEP 397</strong></a>.</p>
|
||
<section id="getting-started">
|
||
<h3><span class="section-number">4.12.1. </span>Getting started<a class="headerlink" href="#getting-started" title="Link to this heading">¶</a></h3>
|
||
<section id="from-the-command-line">
|
||
<h4><span class="section-number">4.12.1.1. </span>From the command-line<a class="headerlink" href="#from-the-command-line" title="Link to this heading">¶</a></h4>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6.</span></p>
|
||
</div>
|
||
<p>System-wide installations of Python 3.3 and later will put the launcher on your
|
||
<span class="target" id="index-38"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code>. The launcher is compatible with all available versions of
|
||
Python, so it does not matter which version is installed. To check that the
|
||
launcher is available, execute the following command in Command Prompt:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>py
|
||
</pre></div>
|
||
</div>
|
||
<p>You should find that the latest version of Python you have installed is
|
||
started - it can be exited as normal, and any additional command-line
|
||
arguments specified will be sent directly to Python.</p>
|
||
<p>If you have multiple versions of Python installed (e.g., 3.7 and 3.15) you
|
||
will have noticed that Python 3.15 was started - to launch Python 3.7, try
|
||
the command:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>py -3.7
|
||
</pre></div>
|
||
</div>
|
||
<p>If you want the latest version of Python 2 you have installed, try the
|
||
command:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>py -2
|
||
</pre></div>
|
||
</div>
|
||
<p>If you see the following error, you do not have the launcher installed:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>'py' is not recognized as an internal or external command,
|
||
operable program or batch file.
|
||
</pre></div>
|
||
</div>
|
||
<p>The command:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>py --list
|
||
</pre></div>
|
||
</div>
|
||
<p>displays the currently installed version(s) of Python.</p>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">-x.y</span></code> argument is the short form of the <code class="docutils literal notranslate"><span class="pre">-V:Company/Tag</span></code> argument,
|
||
which allows selecting a specific Python runtime, including those that may have
|
||
come from somewhere other than python.org. Any runtime registered by following
|
||
<span class="target" id="index-39"></span><a class="pep reference external" href="https://peps.python.org/pep-0514/"><strong>PEP 514</strong></a> will be discoverable. The <code class="docutils literal notranslate"><span class="pre">--list</span></code> command lists all available
|
||
runtimes using the <code class="docutils literal notranslate"><span class="pre">-V:</span></code> format.</p>
|
||
<p>When using the <code class="docutils literal notranslate"><span class="pre">-V:</span></code> argument, specifying the Company will limit selection to
|
||
runtimes from that provider, while specifying only the Tag will select from all
|
||
providers. Note that omitting the slash implies a tag:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># Select any '3.*' tagged runtime
|
||
py -V:3
|
||
|
||
# Select any 'PythonCore' released runtime
|
||
py -V:PythonCore/
|
||
|
||
# Select PythonCore's latest Python 3 runtime
|
||
py -V:PythonCore/3
|
||
</pre></div>
|
||
</div>
|
||
<p>The short form of the argument (<code class="docutils literal notranslate"><span class="pre">-3</span></code>) only ever selects from core Python
|
||
releases, and not other distributions. However, the longer form (<code class="docutils literal notranslate"><span class="pre">-V:3</span></code>) will
|
||
select from any.</p>
|
||
<p>The Company is matched on the full string, case-insensitive. The Tag is matched
|
||
on either the full string, or a prefix, provided the next character is a dot or a
|
||
hyphen. This allows <code class="docutils literal notranslate"><span class="pre">-V:3.1</span></code> to match <code class="docutils literal notranslate"><span class="pre">3.1-32</span></code>, but not <code class="docutils literal notranslate"><span class="pre">3.10</span></code>. Tags are
|
||
sorted using numerical ordering (<code class="docutils literal notranslate"><span class="pre">3.10</span></code> is newer than <code class="docutils literal notranslate"><span class="pre">3.1</span></code>), but are
|
||
compared using text (<code class="docutils literal notranslate"><span class="pre">-V:3.01</span></code> does not match <code class="docutils literal notranslate"><span class="pre">3.1</span></code>).</p>
|
||
</section>
|
||
<section id="virtual-environments">
|
||
<h4><span class="section-number">4.12.1.2. </span>Virtual environments<a class="headerlink" href="#virtual-environments" title="Link to this heading">¶</a></h4>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.5.</span></p>
|
||
</div>
|
||
<p>If the launcher is run with no explicit Python version specification, and a
|
||
virtual environment (created with the standard library <a class="reference internal" href="../library/venv.html#module-venv" title="venv: Creation of virtual environments."><code class="xref py py-mod docutils literal notranslate"><span class="pre">venv</span></code></a> module or
|
||
the external <code class="docutils literal notranslate"><span class="pre">virtualenv</span></code> tool) active, the launcher will run the virtual
|
||
environment’s interpreter rather than the global one. To run the global
|
||
interpreter, either deactivate the virtual environment, or explicitly specify
|
||
the global Python version.</p>
|
||
</section>
|
||
<section id="from-a-script">
|
||
<h4><span class="section-number">4.12.1.3. </span>From a script<a class="headerlink" href="#from-a-script" title="Link to this heading">¶</a></h4>
|
||
<p>Let’s create a test Python script - create a file called <code class="docutils literal notranslate"><span class="pre">hello.py</span></code> with the
|
||
following contents</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="ch">#! python</span>
|
||
<span class="kn">import</span><span class="w"> </span><span class="nn">sys</span>
|
||
<span class="n">sys</span><span class="o">.</span><span class="n">stdout</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s2">"hello from Python </span><span class="si">%s</span><span class="se">\n</span><span class="s2">"</span> <span class="o">%</span> <span class="p">(</span><span class="n">sys</span><span class="o">.</span><span class="n">version</span><span class="p">,))</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>From the directory in which hello.py lives, execute the command:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>py hello.py
|
||
</pre></div>
|
||
</div>
|
||
<p>You should notice the version number of your latest Python 2.x installation
|
||
is printed. Now try changing the first line to be:</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="ch">#! python3</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Re-executing the command should now print the latest Python 3.x information.
|
||
As with the above command-line examples, you can specify a more explicit
|
||
version qualifier. Assuming you have Python 3.7 installed, try changing
|
||
the first line to <code class="docutils literal notranslate"><span class="pre">#!</span> <span class="pre">python3.7</span></code> and you should find the 3.7
|
||
version information printed.</p>
|
||
<p>Note that unlike interactive use, a bare “python” will use the latest
|
||
version of Python 2.x that you have installed. This is for backward
|
||
compatibility and for compatibility with Unix, where the command <code class="docutils literal notranslate"><span class="pre">python</span></code>
|
||
typically refers to Python 2.</p>
|
||
</section>
|
||
<section id="from-file-associations">
|
||
<h4><span class="section-number">4.12.1.4. </span>From file associations<a class="headerlink" href="#from-file-associations" title="Link to this heading">¶</a></h4>
|
||
<p>The launcher should have been associated with Python files (i.e. <code class="docutils literal notranslate"><span class="pre">.py</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">.pyw</span></code>, <code class="docutils literal notranslate"><span class="pre">.pyc</span></code> files) when it was installed. This means that
|
||
when you double-click on one of these files from Windows explorer the launcher
|
||
will be used, and therefore you can use the same facilities described above to
|
||
have the script specify the version which should be used.</p>
|
||
<p>The key benefit of this is that a single launcher can support multiple Python
|
||
versions at the same time depending on the contents of the first line.</p>
|
||
</section>
|
||
</section>
|
||
<section id="id4">
|
||
<h3><span class="section-number">4.12.2. </span>Shebang lines<a class="headerlink" href="#id4" title="Link to this heading">¶</a></h3>
|
||
<p>If the first line of a script file starts with <code class="docutils literal notranslate"><span class="pre">#!</span></code>, it is known as a
|
||
“shebang” line. Linux and other Unix like operating systems have native
|
||
support for such lines and they are commonly used on such systems to indicate
|
||
how a script should be executed. This launcher allows the same facilities to
|
||
be used with Python scripts on Windows and the examples above demonstrate their
|
||
use.</p>
|
||
<p>To allow shebang lines in Python scripts to be portable between Unix and
|
||
Windows, this launcher supports a number of ‘virtual’ commands to specify
|
||
which interpreter to use. The supported virtual commands are:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">/usr/bin/env</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">/usr/bin/python</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">/usr/local/bin/python</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">python</span></code></p></li>
|
||
</ul>
|
||
<p>For example, if the first line of your script starts with</p>
|
||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="ch">#! /usr/bin/python</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The default Python or an active virtual environment will be located and used.
|
||
As many Python scripts written to work on Unix will already have this line,
|
||
you should find these scripts can be used by the launcher without modification.
|
||
If you are writing a new script on Windows which you hope will be useful on
|
||
Unix, you should use one of the shebang lines starting with <code class="docutils literal notranslate"><span class="pre">/usr</span></code>.</p>
|
||
<p>Any of the above virtual commands can be suffixed with an explicit version
|
||
(either just the major version, or the major and minor version).
|
||
Furthermore the 32-bit version can be requested by adding “-32” after the
|
||
minor version. I.e. <code class="docutils literal notranslate"><span class="pre">/usr/bin/python3.7-32</span></code> will request usage of the
|
||
32-bit Python 3.7. If a virtual environment is active, the version will be
|
||
ignored and the environment will be used.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.7: </span>Beginning with python launcher 3.7 it is possible to request 64-bit version
|
||
by the “-64” suffix. Furthermore it is possible to specify a major and
|
||
architecture without minor (i.e. <code class="docutils literal notranslate"><span class="pre">/usr/bin/python3-64</span></code>).</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.11: </span>The “-64” suffix is deprecated, and now implies “any architecture that is
|
||
not provably i386/32-bit”. To request a specific environment, use the new
|
||
<code class="samp docutils literal notranslate"><span class="pre">-V:</span><em><span class="pre">TAG</span></em></code> argument with the complete tag.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.13: </span>Virtual commands referencing <code class="docutils literal notranslate"><span class="pre">python</span></code> now prefer an active virtual
|
||
environment rather than searching <span class="target" id="index-40"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code>. This handles cases where
|
||
the shebang specifies <code class="docutils literal notranslate"><span class="pre">/usr/bin/env</span> <span class="pre">python3</span></code> but <code class="file docutils literal notranslate"><span class="pre">python3.exe</span></code> is
|
||
not present in the active environment.</p>
|
||
</div>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">/usr/bin/env</span></code> form of shebang line has one further special property.
|
||
Before looking for installed Python interpreters, this form will search the
|
||
executable <span class="target" id="index-41"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code> for a Python executable matching the name provided
|
||
as the first argument. This corresponds to the behaviour of the Unix <code class="docutils literal notranslate"><span class="pre">env</span></code>
|
||
program, which performs a <span class="target" id="index-42"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code> search.
|
||
If an executable matching the first argument after the <code class="docutils literal notranslate"><span class="pre">env</span></code> command cannot
|
||
be found, but the argument starts with <code class="docutils literal notranslate"><span class="pre">python</span></code>, it will be handled as
|
||
described for the other virtual commands.
|
||
The environment variable <code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYLAUNCHER_NO_SEARCH_PATH</span></code> may be set
|
||
(to any value) to skip this search of <span class="target" id="index-43"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code>.</p>
|
||
<p>Shebang lines that do not match any of these patterns are looked up in the
|
||
<code class="docutils literal notranslate"><span class="pre">[commands]</span></code> section of the launcher’s <a class="reference internal" href="#launcher-ini"><span class="std std-ref">.INI file</span></a>.
|
||
This may be used to handle certain commands in a way that makes sense for your
|
||
system. The name of the command must be a single argument (no spaces in the
|
||
shebang executable), and the value substituted is the full path to the
|
||
executable (additional arguments specified in the .INI will be quoted as part
|
||
of the filename).</p>
|
||
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[commands]</span>
|
||
<span class="na">/bin/xpython</span><span class="o">=</span><span class="s">C:\Program Files\XPython\python.exe</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Any commands not found in the .INI file are treated as <strong>Windows</strong> executable
|
||
paths that are absolute or relative to the directory containing the script file.
|
||
This is a convenience for Windows-only scripts, such as those generated by an
|
||
installer, since the behavior is not compatible with Unix-style shells.
|
||
These paths may be quoted, and may include multiple arguments, after which the
|
||
path to the script and any additional arguments will be appended.</p>
|
||
</section>
|
||
<section id="arguments-in-shebang-lines">
|
||
<h3><span class="section-number">4.12.3. </span>Arguments in shebang lines<a class="headerlink" href="#arguments-in-shebang-lines" title="Link to this heading">¶</a></h3>
|
||
<p>The shebang lines can also specify additional options to be passed to the
|
||
Python interpreter. For example, if you have a shebang line:</p>
|
||
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="ch">#! /usr/bin/python -v</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Then Python will be started with the <code class="docutils literal notranslate"><span class="pre">-v</span></code> option</p>
|
||
</section>
|
||
<section id="customization">
|
||
<h3><span class="section-number">4.12.4. </span>Customization<a class="headerlink" href="#customization" title="Link to this heading">¶</a></h3>
|
||
<section id="customization-via-ini-files">
|
||
<span id="launcher-ini"></span><h4><span class="section-number">4.12.4.1. </span>Customization via INI files<a class="headerlink" href="#customization-via-ini-files" title="Link to this heading">¶</a></h4>
|
||
<p>Two .ini files will be searched by the launcher - <code class="docutils literal notranslate"><span class="pre">py.ini</span></code> in the current
|
||
user’s application data directory (<code class="docutils literal notranslate"><span class="pre">%LOCALAPPDATA%</span></code> or <code class="docutils literal notranslate"><span class="pre">$env:LocalAppData</span></code>)
|
||
and <code class="docutils literal notranslate"><span class="pre">py.ini</span></code> in the same directory as the launcher. The same .ini files are
|
||
used for both the ‘console’ version of the launcher (i.e. py.exe) and for the
|
||
‘windows’ version (i.e. pyw.exe).</p>
|
||
<p>Customization specified in the “application directory” will have precedence over
|
||
the one next to the executable, so a user, who may not have write access to the
|
||
.ini file next to the launcher, can override commands in that global .ini file.</p>
|
||
</section>
|
||
<section id="customizing-default-python-versions">
|
||
<h4><span class="section-number">4.12.4.2. </span>Customizing default Python versions<a class="headerlink" href="#customizing-default-python-versions" title="Link to this heading">¶</a></h4>
|
||
<p>In some cases, a version qualifier can be included in a command to dictate
|
||
which version of Python will be used by the command. A version qualifier
|
||
starts with a major version number and can optionally be followed by a period
|
||
(‘.’) and a minor version specifier. Furthermore it is possible to specify
|
||
if a 32 or 64 bit implementation shall be requested by adding “-32” or “-64”.</p>
|
||
<p>For example, a shebang line of <code class="docutils literal notranslate"><span class="pre">#!python</span></code> has no version qualifier, while
|
||
<code class="docutils literal notranslate"><span class="pre">#!python3</span></code> has a version qualifier which specifies only a major version.</p>
|
||
<p>If no version qualifiers are found in a command, the environment
|
||
variable <code class="xref std std-envvar docutils literal notranslate"><span class="pre">PY_PYTHON</span></code> can be set to specify the default version
|
||
qualifier. If it is not set, the default is “3”. The variable can
|
||
specify any value that may be passed on the command line, such as “3”,
|
||
“3.7”, “3.7-32” or “3.7-64”. (Note that the “-64” option is only
|
||
available with the launcher included with Python 3.7 or newer.)</p>
|
||
<p>If no minor version qualifiers are found, the environment variable
|
||
<code class="docutils literal notranslate"><span class="pre">PY_PYTHON{major}</span></code> (where <code class="docutils literal notranslate"><span class="pre">{major}</span></code> is the current major version qualifier
|
||
as determined above) can be set to specify the full version. If no such option
|
||
is found, the launcher will enumerate the installed Python versions and use
|
||
the latest minor release found for the major version, which is likely,
|
||
although not guaranteed, to be the most recently installed version in that
|
||
family.</p>
|
||
<p>On 64-bit Windows with both 32-bit and 64-bit implementations of the same
|
||
(major.minor) Python version installed, the 64-bit version will always be
|
||
preferred. This will be true for both 32-bit and 64-bit implementations of the
|
||
launcher - a 32-bit launcher will prefer to execute a 64-bit Python installation
|
||
of the specified version if available. This is so the behavior of the launcher
|
||
can be predicted knowing only what versions are installed on the PC and
|
||
without regard to the order in which they were installed (i.e., without knowing
|
||
whether a 32 or 64-bit version of Python and corresponding launcher was
|
||
installed last). As noted above, an optional “-32” or “-64” suffix can be
|
||
used on a version specifier to change this behaviour.</p>
|
||
<p>Examples:</p>
|
||
<ul class="simple">
|
||
<li><p>If no relevant options are set, the commands <code class="docutils literal notranslate"><span class="pre">python</span></code> and
|
||
<code class="docutils literal notranslate"><span class="pre">python2</span></code> will use the latest Python 2.x version installed and
|
||
the command <code class="docutils literal notranslate"><span class="pre">python3</span></code> will use the latest Python 3.x installed.</p></li>
|
||
<li><p>The command <code class="docutils literal notranslate"><span class="pre">python3.7</span></code> will not consult any
|
||
options at all as the versions are fully specified.</p></li>
|
||
<li><p>If <code class="docutils literal notranslate"><span class="pre">PY_PYTHON=3</span></code>, the commands <code class="docutils literal notranslate"><span class="pre">python</span></code> and <code class="docutils literal notranslate"><span class="pre">python3</span></code> will both use
|
||
the latest installed Python 3 version.</p></li>
|
||
<li><p>If <code class="docutils literal notranslate"><span class="pre">PY_PYTHON=3.7-32</span></code>, the command <code class="docutils literal notranslate"><span class="pre">python</span></code> will use the 32-bit
|
||
implementation of 3.7 whereas the command <code class="docutils literal notranslate"><span class="pre">python3</span></code> will use the latest
|
||
installed Python (PY_PYTHON was not considered at all as a major
|
||
version was specified.)</p></li>
|
||
<li><p>If <code class="docutils literal notranslate"><span class="pre">PY_PYTHON=3</span></code> and <code class="docutils literal notranslate"><span class="pre">PY_PYTHON3=3.7</span></code>, the commands
|
||
<code class="docutils literal notranslate"><span class="pre">python</span></code> and <code class="docutils literal notranslate"><span class="pre">python3</span></code> will both use specifically 3.7</p></li>
|
||
</ul>
|
||
<p>In addition to environment variables, the same settings can be configured
|
||
in the .INI file used by the launcher. The section in the INI file is
|
||
called <code class="docutils literal notranslate"><span class="pre">[defaults]</span></code> and the key name will be the same as the
|
||
environment variables without the leading <code class="docutils literal notranslate"><span class="pre">PY_</span></code> prefix (and note that
|
||
the key names in the INI file are case insensitive.) The contents of
|
||
an environment variable will override things specified in the INI file.</p>
|
||
<p>For example:</p>
|
||
<ul class="simple">
|
||
<li><p>Setting <code class="docutils literal notranslate"><span class="pre">PY_PYTHON=3.7</span></code> is equivalent to the INI file containing:</p></li>
|
||
</ul>
|
||
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[defaults]</span>
|
||
<span class="na">python</span><span class="o">=</span><span class="s">3.7</span>
|
||
</pre></div>
|
||
</div>
|
||
<ul class="simple">
|
||
<li><p>Setting <code class="docutils literal notranslate"><span class="pre">PY_PYTHON=3</span></code> and <code class="docutils literal notranslate"><span class="pre">PY_PYTHON3=3.7</span></code> is equivalent to the INI file
|
||
containing:</p></li>
|
||
</ul>
|
||
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[defaults]</span>
|
||
<span class="na">python</span><span class="o">=</span><span class="s">3</span>
|
||
<span class="na">python3</span><span class="o">=</span><span class="s">3.7</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
<section id="diagnostics">
|
||
<h3><span class="section-number">4.12.5. </span>Diagnostics<a class="headerlink" href="#diagnostics" title="Link to this heading">¶</a></h3>
|
||
<p>If an environment variable <code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYLAUNCHER_DEBUG</span></code> is set (to any value), the
|
||
launcher will print diagnostic information to stderr (i.e. to the console).
|
||
While this information manages to be simultaneously verbose <em>and</em> terse, it
|
||
should allow you to see what versions of Python were located, why a
|
||
particular version was chosen and the exact command-line used to execute the
|
||
target Python. It is primarily intended for testing and debugging.</p>
|
||
</section>
|
||
<section id="dry-run">
|
||
<h3><span class="section-number">4.12.6. </span>Dry run<a class="headerlink" href="#dry-run" title="Link to this heading">¶</a></h3>
|
||
<p>If an environment variable <code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYLAUNCHER_DRYRUN</span></code> is set (to any value),
|
||
the launcher will output the command it would have run, but will not actually
|
||
launch Python. This may be useful for tools that want to use the launcher to
|
||
detect and then launch Python directly. Note that the command written to
|
||
standard output is always encoded using UTF-8, and may not render correctly in
|
||
the console.</p>
|
||
</section>
|
||
<section id="install-on-demand">
|
||
<h3><span class="section-number">4.12.7. </span>Install on demand<a class="headerlink" href="#install-on-demand" title="Link to this heading">¶</a></h3>
|
||
<p>If an environment variable <code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYLAUNCHER_ALLOW_INSTALL</span></code> is set (to any
|
||
value), and the requested Python version is not installed but is available on
|
||
the Microsoft Store, the launcher will attempt to install it. This may require
|
||
user interaction to complete, and you may need to run the command again.</p>
|
||
<p>An additional <code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYLAUNCHER_ALWAYS_INSTALL</span></code> variable causes the launcher
|
||
to always try to install Python, even if it is detected. This is mainly intended
|
||
for testing (and should be used with <code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYLAUNCHER_DRYRUN</span></code>).</p>
|
||
</section>
|
||
<section id="return-codes">
|
||
<h3><span class="section-number">4.12.8. </span>Return codes<a class="headerlink" href="#return-codes" title="Link to this heading">¶</a></h3>
|
||
<p>The following exit codes may be returned by the Python launcher. Unfortunately,
|
||
there is no way to distinguish these from the exit code of Python itself.</p>
|
||
<p>The names of codes are as used in the sources, and are only for reference. There
|
||
is no way to access or resolve them apart from reading this page. Entries are
|
||
listed in alphabetical order of names.</p>
|
||
<table class="docutils align-default">
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>Name</p></th>
|
||
<th class="head"><p>Value</p></th>
|
||
<th class="head"><p>Description</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p>RC_BAD_VENV_CFG</p></td>
|
||
<td><p>107</p></td>
|
||
<td><p>A <code class="file docutils literal notranslate"><span class="pre">pyvenv.cfg</span></code> was found but is corrupt.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>RC_CREATE_PROCESS</p></td>
|
||
<td><p>101</p></td>
|
||
<td><p>Failed to launch Python.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>RC_INSTALLING</p></td>
|
||
<td><p>111</p></td>
|
||
<td><p>An install was started, but the command will
|
||
need to be re-run after it completes.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>RC_INTERNAL_ERROR</p></td>
|
||
<td><p>109</p></td>
|
||
<td><p>Unexpected error. Please report a bug.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>RC_NO_COMMANDLINE</p></td>
|
||
<td><p>108</p></td>
|
||
<td><p>Unable to obtain command line from the
|
||
operating system.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>RC_NO_PYTHON</p></td>
|
||
<td><p>103</p></td>
|
||
<td><p>Unable to locate the requested version.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>RC_NO_VENV_CFG</p></td>
|
||
<td><p>106</p></td>
|
||
<td><p>A <code class="file docutils literal notranslate"><span class="pre">pyvenv.cfg</span></code> was required but not
|
||
found.</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</section>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
<div class="clearer"></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="Main">
|
||
<div class="sphinxsidebarwrapper">
|
||
<div>
|
||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#">4. Using Python on Windows</a><ul>
|
||
<li><a class="reference internal" href="#python-install-manager">4.1. Python install manager</a><ul>
|
||
<li><a class="reference internal" href="#installation">4.1.1. Installation</a></li>
|
||
<li><a class="reference internal" href="#basic-use">4.1.2. Basic use</a></li>
|
||
<li><a class="reference internal" href="#command-help">4.1.3. Command help</a></li>
|
||
<li><a class="reference internal" href="#listing-runtimes">4.1.4. Listing runtimes</a></li>
|
||
<li><a class="reference internal" href="#installing-runtimes">4.1.5. Installing runtimes</a></li>
|
||
<li><a class="reference internal" href="#offline-installs">4.1.6. Offline installs</a></li>
|
||
<li><a class="reference internal" href="#uninstalling-runtimes">4.1.7. Uninstalling runtimes</a></li>
|
||
<li><a class="reference internal" href="#configuration">4.1.8. Configuration</a></li>
|
||
<li><a class="reference internal" href="#shebang-lines">4.1.9. Shebang lines</a></li>
|
||
<li><a class="reference internal" href="#advanced-installation">4.1.10. Advanced installation</a></li>
|
||
<li><a class="reference internal" href="#administrative-configuration">4.1.11. Administrative configuration</a></li>
|
||
<li><a class="reference internal" href="#installing-free-threaded-binaries">4.1.12. Installing free-threaded binaries</a></li>
|
||
<li><a class="reference internal" href="#index-signatures">4.1.13. Index signatures</a></li>
|
||
<li><a class="reference internal" href="#proxy-settings">4.1.14. Proxy settings</a></li>
|
||
<li><a class="reference internal" href="#troubleshooting">4.1.15. Troubleshooting</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#the-embeddable-package">4.2. The embeddable package</a><ul>
|
||
<li><a class="reference internal" href="#python-application">4.2.1. Python application</a></li>
|
||
<li><a class="reference internal" href="#embedding-python">4.2.2. Embedding Python</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#the-nuget-org-packages">4.3. The nuget.org packages</a><ul>
|
||
<li><a class="reference internal" href="#free-threaded-packages">4.3.1. Free-threaded packages</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#alternative-bundles">4.4. Alternative bundles</a></li>
|
||
<li><a class="reference internal" href="#supported-windows-versions">4.5. Supported Windows versions</a></li>
|
||
<li><a class="reference internal" href="#removing-the-max-path-limitation">4.6. Removing the MAX_PATH limitation</a></li>
|
||
<li><a class="reference internal" href="#utf-8-mode">4.7. UTF-8 mode</a></li>
|
||
<li><a class="reference internal" href="#finding-modules">4.8. Finding modules</a></li>
|
||
<li><a class="reference internal" href="#additional-modules">4.9. Additional modules</a><ul>
|
||
<li><a class="reference internal" href="#pywin32">4.9.1. PyWin32</a></li>
|
||
<li><a class="reference internal" href="#cx-freeze">4.9.2. cx_Freeze</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#compiling-python-on-windows">4.10. Compiling Python on Windows</a></li>
|
||
<li><a class="reference internal" href="#the-full-installer-deprecated">4.11. The full installer (deprecated)</a><ul>
|
||
<li><a class="reference internal" href="#installation-steps">4.11.1. Installation steps</a></li>
|
||
<li><a class="reference internal" href="#id2">4.11.2. Removing the MAX_PATH limitation</a></li>
|
||
<li><a class="reference internal" href="#installing-without-ui">4.11.3. Installing without UI</a></li>
|
||
<li><a class="reference internal" href="#installing-without-downloading">4.11.4. Installing without downloading</a></li>
|
||
<li><a class="reference internal" href="#modifying-an-install">4.11.5. Modifying an install</a></li>
|
||
<li><a class="reference internal" href="#id3">4.11.6. Installing free-threaded binaries</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#python-launcher-for-windows-deprecated">4.12. Python launcher for Windows (deprecated)</a><ul>
|
||
<li><a class="reference internal" href="#getting-started">4.12.1. Getting started</a><ul>
|
||
<li><a class="reference internal" href="#from-the-command-line">4.12.1.1. From the command-line</a></li>
|
||
<li><a class="reference internal" href="#virtual-environments">4.12.1.2. Virtual environments</a></li>
|
||
<li><a class="reference internal" href="#from-a-script">4.12.1.3. From a script</a></li>
|
||
<li><a class="reference internal" href="#from-file-associations">4.12.1.4. From file associations</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#id4">4.12.2. Shebang lines</a></li>
|
||
<li><a class="reference internal" href="#arguments-in-shebang-lines">4.12.3. Arguments in shebang lines</a></li>
|
||
<li><a class="reference internal" href="#customization">4.12.4. Customization</a><ul>
|
||
<li><a class="reference internal" href="#customization-via-ini-files">4.12.4.1. Customization via INI files</a></li>
|
||
<li><a class="reference internal" href="#customizing-default-python-versions">4.12.4.2. Customizing default Python versions</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#diagnostics">4.12.5. Diagnostics</a></li>
|
||
<li><a class="reference internal" href="#dry-run">4.12.6. Dry run</a></li>
|
||
<li><a class="reference internal" href="#install-on-demand">4.12.7. Install on demand</a></li>
|
||
<li><a class="reference internal" href="#return-codes">4.12.8. Return codes</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
<div>
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="configure.html"
|
||
title="previous chapter"><span class="section-number">3. </span>Configure Python</a></p>
|
||
</div>
|
||
<div>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="mac.html"
|
||
title="next chapter"><span class="section-number">5. </span>Using Python on macOS</a></p>
|
||
</div>
|
||
<script>
|
||
document.addEventListener('DOMContentLoaded', () => {
|
||
const title = document.querySelector('meta[property="og:title"]').content;
|
||
const elements = document.querySelectorAll('.improvepage');
|
||
const pageurl = window.location.href.split('?')[0];
|
||
elements.forEach(element => {
|
||
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
|
||
url.searchParams.set('pagetitle', title);
|
||
url.searchParams.set('pageurl', pageurl);
|
||
url.searchParams.set('pagesource', "using/windows.rst");
|
||
element.href = url.toString();
|
||
});
|
||
});
|
||
</script>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">Report a bug</a></li>
|
||
<li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.15/Doc/using/windows.rst?plain=1"
|
||
rel="nofollow">Show source
|
||
</a>
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
<div id="sidebarbutton" title="Collapse sidebar">
|
||
<span>«</span>
|
||
</div>
|
||
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="Related">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
>index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="mac.html" title="5. Using Python on macOS"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="configure.html" title="3. Configure Python"
|
||
>previous</a> |</li>
|
||
|
||
<li class="root-icon"><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.15.0 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >Python Setup and Usage</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href=""><span class="section-number">4. </span>Using Python on Windows</a></li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
|
||
<input type="submit" value="Go">
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
<li class="right">
|
||
<label class="theme-selector-label">
|
||
Theme
|
||
<select class="theme-selector" oninput="activateTheme(this.value)">
|
||
<option value="auto" selected>Auto</option>
|
||
<option value="light">Light</option>
|
||
<option value="dark">Dark</option>
|
||
</select>
|
||
</label> |</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
© <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.
|
||
<br>
|
||
This page is licensed under the Python Software Foundation License Version 2.
|
||
<br>
|
||
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
|
||
<br>
|
||
|
||
See <a href="/license.html">History and License</a> for more information.<br>
|
||
|
||
|
||
<br>
|
||
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br>
|
||
<br>
|
||
Last updated on Oct 09, 2026 (11:35 UTC).
|
||
|
||
<a href="/bugs.html">Found a bug</a>?
|
||
|
||
<br>
|
||
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |