PEP 514 – Python registration in the Windows registry
- Author:
- Steve Dower <steve.dower at python.org>
- BDFL-Delegate:
- Paul Moore <p.f.moore at gmail.com>
- Status:
- Active
- Type:
- Informational
- Created:
- 02-Feb-2016
- Post-History:
- 02-Feb-2016, 01-Mar-2016, 18-Jul-2016
- Resolution:
- Python-Dev message
Abstract
This PEP defines a schema for the Python registry key to allow third-party installers to register their installation, and to allow tools and applications to detect and correctly display all Python environments on a user’s machine. No implementation changes to Python are proposed with this PEP.
Python environments are not required to be registered unless they want to be automatically discoverable by external tools. As this relates to Windows only, these tools are expected to be predominantly GUI applications. However, console applications may also make use of the registered information. This PEP covers the information that may be made available, but the actual presentation and use of this information is left to the tool designers.
The schema matches the registry values that have been used by the official installer since at least Python 2.5, and the resolution behaviour matches the behaviour of the official Python releases. Some backwards compatibility rules are provided to ensure tools can correctly detect versions of CPython that do not register full information.
Motivation
When installed on Windows, the official Python installer creates a registry key
for discovery and detection by other applications. This allows tools such as
installers or IDEs to automatically detect and display a user’s Python
installations. For example, the PEP 397 py.exe launcher and editors such as
PyCharm and Visual Studio already make use of this information.
Third-party installers, such as those used by distributions, typically create identical keys for the same purpose. Most tools that use the registry to detect Python installations only inspect the keys used by the official installer. As a result, third-party installations that wish to be discoverable will overwrite these values, often causing users to “lose” their original Python installation.
By describing a layout for registry keys that allows third-party installations to register themselves uniquely, as well as providing tool developers guidance for discovering all available Python installations, these collisions should be prevented. We also take the opportunity to add some well-known metadata so that more information can be presented to users.
Definitions
A “registry key” is the equivalent of a file-system path into the registry. Each key may contain “subkeys” (keys nested within keys) and “values” (named and typed attributes attached to a key). These are used on Windows to store settings in much the same way that directories containing configuration files would work.
HKEY_CURRENT_USER is the root of settings for the currently logged-in user,
and this user can generally read and write all settings under this root.
HKEY_LOCAL_MACHINE is the root of settings for all users. Generally, any
user can read these settings but only administrators can modify them. It is
typical for values under HKEY_CURRENT_USER to take precedence over those in
HKEY_LOCAL_MACHINE.
On 64-bit Windows, HKEY_LOCAL_MACHINE\Software\Wow6432Node is a special key
that 32-bit processes transparently read and write to rather than accessing the
Software key directly.
Further documentation regarding registry redirection on Windows is available from the MSDN Library [1].
Structure
We consider there to be a single collection of Python environments on a machine, where the collection may be different for each user of the machine. There are three potential registry locations where the collection may be stored based on the installation options of each environment:
HKEY_CURRENT_USER\Software\Python\<Company>\<Tag>
HKEY_LOCAL_MACHINE\Software\Python\<Company>\<Tag>
HKEY_LOCAL_MACHINE\Software\Wow6432Node\Python\<Company>\<Tag>
Official Python releases use PythonCore for Company, and the value of
sys.winver for Tag. The Company PyLauncher is reserved. Other registered
environments may use any values for Company and Tag. Recommendations are made
later in this document.
Company-Tag pairs are case-insensitive, and uniquely identify each environment. Depending on the purpose and intended use of a tool, there are two suggested approaches for resolving conflicts between Company-Tag pairs.
Tools that list every installed environment may choose to include those even where the Company-Tag pairs match. They should ensure users can easily identify whether the registration was per-user or per-machine, and which registration has the higher priority.
Tools that aim to select a single installed environment from all registered
environments based on the Company-Tag pair, such as the py.exe launcher,
should always select the environment registered in HKEY_CURRENT_USER
instead of the matching one in HKEY_LOCAL_MACHINE.
Conflicts between HKEY_LOCAL_MACHINE\Software\Python and
HKEY_LOCAL_MACHINE\Software\Wow6432Node\Python should only occur when both
64-bit and 32-bit versions of an interpreter have the same Tag. In this case,
the tool should select whichever is more appropriate for its use.
If a tool is able to determine from the provided information (or lack thereof) that it cannot use a registered environment, there is no obligation to present it to users.
Except as discussed in the section on backwards compatibility, Company and Tag values are considered opaque to tools, and no information about the interpreter should be inferred from the text. However, some tools may display the Company and Tag values to users, so ideally the Tag will be able to help users identify the associated environment.
Python environments are not required to register themselves unless they want to be automatically discoverable by external tools.
Backwards Compatibility
Python 3.4 and earlier did not distinguish between 32-bit and 64-bit builds in
sys.winver. As a result, it is not possible to have valid side-by-side
installations of both 32-bit and 64-bit interpreters under this scheme since it
would result in duplicate Tags.
To ensure backwards compatibility, applications should treat environments listed under the following two registry keys as distinct, even when the Tag matches:
HKEY_LOCAL_MACHINE\Software\Python\PythonCore\<Tag>
HKEY_LOCAL_MACHINE\Software\Wow6432Node\Python\PythonCore\<Tag>
Environments listed under HKEY_CURRENT_USER may be treated as distinct from
both of the above keys, potentially resulting in three environments discovered
using the same Tag. Alternatively, a tool may determine whether the per-user
environment is 64-bit or 32-bit and give it priority over the per-machine
environment, resulting in a maximum of two discovered environments.
It is not possible to detect side-by-side installations of both 64-bit and 32-bit versions of Python prior to 3.5 when they have been installed for the current user. Python 3.5 and later always uses different Tags for 64-bit and 32-bit versions.
The following section describe user-visible information that may be registered.
For Python 3.5 and earlier, none of this information is available, but
alternative defaults are specified for the PythonCore key.
Environments registered under other Company names have no backward compatibility requirements and must use distinct Tags to support side-by-side installations. Tools consuming these registrations are not required to disambiguate tags other than by preferring the user’s setting.
Company
The Company part of the key is intended to group related environments and to ensure that Tags are namespaced appropriately. The key name should be alphanumeric without spaces and likely to be unique. For example, a trademarked name (preferred), a hostname, or as a last resort, a UUID would be appropriate:
HKEY_CURRENT_USER\Software\Python\ExampleCorp
HKEY_CURRENT_USER\Software\Python\www.example.com
HKEY_CURRENT_USER\Software\Python\6C465E66-5A8C-4942-9E6A-D29159480C60
The company name PyLauncher is reserved for the PEP 397 launcher
(py.exe). It does not follow this convention and should be ignored by tools.
If a string value named DisplayName exists, it should be used to identify
the environment manufacturer/developer/distributor to users. Otherwise, the name
of the key should be used. (For PythonCore, the default display name is
“Python Software Foundation”.)
If a string value named SupportUrl exists, it may be displayed or otherwise
used to direct users to a web site related to the environment. (For
PythonCore, the default support URL is “http://www.python.org/”.)
A complete example may look like:
HKEY_CURRENT_USER\Software\