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\Python\ExampleCorp
    (Default) = (value not set)
    DisplayName = "Example Corp"
    SupportUrl = "http://www.example.com"

Tag

The Tag part of the key is intended to uniquely identify an environment within those provided by a single company. The key name should be alphanumeric without spaces and stable across installations. For example, the Python language version, a UUID or a partial/complete hash would be appropriate, while a Tag based on the install directory or some aspect of the current machine may not. For example:

HKEY_CURRENT_USER\Software\Python\ExampleCorp\examplepy
HKEY_CURRENT_USER\Software\Python\ExampleCorp\3.6
HKEY_CURRENT_USER\Software\Python\ExampleCorp\6C465E66

It is expected that some tools will require users to type the Tag into a command line, and that the Company may be optional provided the Tag is unique across all Python installations. Short, human-readable and easy to type Tags are recommended, and if possible, select a value likely to be unique across all other Companies.

If a string value named DisplayName exists, it should be used to identify the environment to users. Otherwise, the name of the key should be used. (For PythonCore, the default is “Python ” followed by the Tag.)

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 is “http://www.python.org/”.)

If a string value named Version exists, it should be used to identify the version of the environment. This is independent from the version of Python implemented by the environment. (For PythonCore, the default is the first three characters of the Tag.)

If a string value named SysVersion exists, it must be in x.y or x.y.z format matching the version returned by sys.version_info in the interpreter. If omitted, the Python version is unknown. (For PythonCore, the default is the first three characters of the Tag.)

If a string value named SysArchitecture exists, it must match the first element of the tuple returned by platform.architecture(). Typically, this will be “32bit” or “64bit”. If omitted, the architecture is unknown. (For PythonCore, the architecture is “32bit” when registered under HKEY_LOCAL_MACHINE\Software\Wow6432Node\Python or anywhere on a 32-bit operating system, “64bit” when registered under HKEY_LOCAL_MACHINE\Software\Python on a 64-bit machine, and unknown when registered under HKEY_CURRENT_USER.)

Note that each of these values is recommended, but optional. Omitting SysVersion or SysArchitecture may prevent some tools from correctly supporting the environment. A complete example may look like this:

HKEY_CURRENT_USER\Software\Python\ExampleCorp\examplepy
    (Default) = (value not set)
    DisplayName = "Example Py Distro 3"
    SupportUrl = "http://www.example.com/distro-3"
    Version = "3.0.12345.0"
    SysVersion = "3.6.0"
    SysArchitecture = "64bit"

InstallPath

Beneath the environment key, an InstallPath key must be created. This key is always named InstallPath, and the default value must match sys.prefix:

HKEY_CURRENT_USER\Software\Python\ExampleCorp\3.6\InstallPath
    (Default) = "C:\ExampleCorpPy36"

If a string value named ExecutablePath exists, it must be the full path to the python.exe (or equivalent) executable. If omitted, the environment is not executable. (For PythonCore, the default is the python.exe file in the directory referenced by the (Default) value.)

If a string value named ExecutableArguments exists, tools should use the value as the first arguments when executing ExecutablePath. Tools may add other arguments following these, and will reasonably expect standard Python command line options to be available.

If a string value named WindowedExecutablePath exists, it must be a path to the pythonw.exe (or equivalent) executable. If omitted, the default is the value of ExecutablePath, and if that is omitted the environment is not executable. (For PythonCore, the default is the pythonw.exe file in the directory referenced by the (Default) value.)

If a string value named WindowedExecutableArguments exists, tools should use the value as the first arguments when executing WindowedExecutablePath. Tools may add other arguments following these, and will reasonably expect standard Python command line options to be available.

A complete example may look like:

HKEY_CURRENT_USER\Software\Python\ExampleCorp\examplepy\InstallPath
    (Default) = "C:\ExampleDistro30"
    ExecutablePath = "C:\ExampleDistro30\ex_python.exe"
    ExecutableArguments = "--arg1"
    WindowedExecutablePath = "C:\ExampleDistro30\ex_pythonw.exe"
    WindowedExecutableArguments = "--arg1"

Help

Beneath the environment key, a Help key may be created. This key is always named Help if present and has no default value.

Each subkey of Help specifies a documentation file, tool, or URL associated with the environment. The subkey may have any name, and the default value is a string appropriate for passing to os.startfile or equivalent.

If a string value named DisplayName exists, it should be used to identify the help file to users. Otherwise, the key name should be used.

A complete example may look like:

HKEY_CURRENT_USER\Software\Python\ExampleCorp\6C465E66\Help
    Python\
        (Default) = "C:\ExampleDistro30\python36.chm"
        DisplayName = "Python Documentation"
    Extras\
        (Default) = "http://www.example.com/tutorial"
        DisplayName = "Example Distro Online Tutorial"

Other Keys

All other subkeys under a Company-Tag pair are available for private use.

Official CPython releases have traditionally used certain keys in this space to determine the location of the Python standard library and other installed modules. This behaviour is retained primarily for backward compatibility. However, as the code that reads these values is embedded into the interpreter, third-party distributions may be affected by values written into PythonCore if using an unmodified interpreter.