PEP 773 – A Python Installation Manager for Windows | peps.python.org
PEP 773 – A Python Installation Manager for Windows PEP 773 – A Python Installation Manager for Windows Author : Steve Dower Discussions-To : Discourse thread Status : Final Type : Standards Track Topic : Release Created : 21-Jan-2025 Post-History : 18-Dec-2024 , 21-Jan-2025 Replaces : 397 , 486 Resolution : 25-Apr-2025 Table of Contents Abstract Reader’s Note Background Expectations Traditional Installer Windows Store NuGet Package Embeddable Package Alternate Distributions Challenges Overview of PyManager Replacing other installers Project ownership and development Specification Exec subcommand Install subcommand Uninstall subcommand List subcommand Help subcommand Environment Variables Start Menu Shortcuts File Associations Windowed Executables Configuration Index Schema Shebang Processing Rationale “Changing” the python.exe command Replacing py.exe Interaction with venv Backwards Compatibility Scripted downloads Scripted installs Old runtime installed Old py.exe launcher installed Misconfigured venv activated Old version availability Administrator installs Build-time installs Single architecture installer Test suite and debug symbols Global pip command Security Implications Impact on Existing PEPs How to Teach This Basic Use Uninstallation Configuration Custom Index Reference Implementation Rejected Ideas Make PyManager available on all platforms Include a runtime pre-installed with the manager Include a runtime INSTEAD OF the manager Use a built-in module rather than subcommands Use a new command-line option rather than subcommands Improving the current traditional installer instead Delete the Store package completely Rely on WinGet or equivalents Make every version a Windows Store package Just publish the plain ZIP file Only publish PyManager to one place Inline Script Metadata Copyright Important This PEP is a historical document.
The up-to-date, canonical documentation can now be found at Python Releases for Windows . × See PEP 1 for how to propose changes. Abstract Installation of the python.org Python distribution on Windows is complex. There are three main approaches with roughly equivalent levels of user experience, and yet all of these suffer from different limitations, including failing to satisfy modern usage scenarios. This PEP proposes a design for a single Windows install workflow tool that satisfies all the needs of the existing installers for the platform, while avoiding most of their limitations, and provides the core team with the ability to manage releases for many years to come.
With the new installer, the recommended command to launch the default Python on Windows will be python , while the command for managing multiple versions (including launching a specific one) will be py . Users can also opt-in to having global python3.x commands by adding an extra entry to their PATH environment variable. We recommend starting with the “How to teach this” section for the most concise high-level overview of the features.
The existing .exe installer and py launcher will be deprecated and no longer released from two years after this PEP is accepted. The existing embeddable distro will no longer be listed as a download, but will be available through the install manager. The Windows Store app will be immediately replaced with the install manager. Reader’s Note This document is a detailed proposal , intended to assist in an “approve” or “reject” decision on the replacement of the existing install formats for Python on Windows with a new format.
It is not intended to be a binding specification, nor is it user documentation or an interoperability specification. The actual implementation may vary over time as needs change, and that is not to be considered a “violation” of this PEP. Any interfaces and protocols meant for public use will be independently documented and maintained in accordance with standard deprecation timelines. Documentation on installing Python on Windows can be found at docs.python.org/using/windows.html .
Background There are a large range of needs users may have that lead to them wanting to install a Python runtime. Many, likely most, are interested in running (perhaps writing) short scripts, such as those that perform a simple task, or help teach someone a concept. Some users are looking for a specific version to integrate with existing code or another application. Some are after a full set of different interpreter versions to perform testing.
In this section, we discuss the expectations that users have of “installing Python”, provide an overview of the existing installers for Windows, and identify some of the gaps and challenges inherent in these offerings. Expectations Based on significant anecdotal experience and analysis of quantitative data available (though not necessarily public), we make the following assertions about the majority of Python users on Windows: most users just want the latest stable version most users want a “one-click” (or fewer) install most users do not want to use administrator privileges most users will benefit from installing maintenance updates most users expect the python command to work after installation The primary support for these assertions is that the most popular installers actively chosen by users are the latest stable release on python.org, and the latest stable release on the Windows Store, both of which meet these requirements.
We make the following assumptions about other significant sets of users. These may have some overlap between groups, and at least some users expect all of them. some users want to install Python programmatically some users want to install a particular version some users want to install many versions some users want to install for all users of their machine some users do not want Start Menu shortcuts some users want to install as part of their project’s build process some users want to install as part of their project’s install process some users intend to never update their install some users expect the py command to work after installation These assumptions have all been demonstrated over time to exist, though the relative importance has not been quantified.
The NuGet packages and the embeddable distro can meet most of these needs. Traditional Installer The traditional installer is an executable downloadable directly from python.org that installs the entire development kit for Python. This includes the CPython interpreter, the standard library, Python headers and import libraries, builds of Tcl and Tk, the documentation as HTML files, the runtime and standard library test suite, Start Menu shortcuts for Python and IDLE, debugging symbols and debug builds of the binaries, the py.exe launcher and its file associations, and functionality to modify the user’s PATH environment variable, enable long-path support on their system, pre-generate .pyc files for the standard library, and install pip.
As of 3.13, it also includes a set of experimental free-threaded binaries. Many of these components are optional. After downloading the executable, users are presented with a “quick install” option, which installs into their user directory with most options enabled. We believe that most users select this option. A second option alongside the quick install takes the user to two pages worth of options, listing the components that they need not install, as well as other options such as the install directory and whether to install for all users.
All of these options may be specified on the command line, and there is also an option to proceed with the install without displaying any UI. Based on feedback and bug reports, all of these options are used by at least some users. However, as we do not track install telemetry, we have no way to know which options are more important than others. Behind the scenes, the traditional installer is a Burn bundle, generated using the Wix Toolset installer framework, containing one or more MSI fil
The rest of this page is on the live site.