Quick Build Info ================ For testing, the installer should be built with the Tools/msi/build.bat script: build.bat [-x86] [-x64] [--doc] For an official release, the installer should be built with the Tools/msi/buildrelease.bat script and environment variables: set PYTHON= set SPHINXBUILD= set PATH=; ;%PATH% buildrelease.bat [-x86] [-x64] [-D] [-B] [-o ] [-c ] See the Building the Installer section for more information. Overview ======== Python is distributed on Windows as an installer that will configure the user's system. This allows users to have a functioning copy of Python without having to build it themselves. The main tasks of the installer are: * copy required files into the expected layout * configure system settings so the installation can be located by other programs * add entry points for modifying, repairing and uninstalling Python * make it easy to launch Python, its documentation, and IDLE Each of these is discussed in a later section of this document. Structure of the Installer ========================== The installer is structured as a 'layout', which consists of a number of CAB and MSI files and a single EXE. The EXE is the main entry point into the installer. It contains the UI and command-line logic, as well as the ability to locate and optionally download other parts of the layout. Each MSI contains the logic required to install a component or feature of Python. These MSIs should not be launched directly by users. MSIs can be embedded into the EXE or automatically downloaded as needed. Each CAB contains the files making up a Python installation. CABs can be embedded into the EXE or automatically downloaded as needed. MSIs and CABs are only required when the related feature or component is being installed. When components are not selected for installation, the associated MSI and CAB are not needed and will not be downloaded. This allows the installer to offer options to install debugging symbols and binaries without the significant increase in download size that would be required with a single MSI. Building the Installer ====================== For testing, the installer should be built with the Tools/msi/build.bat script: build.bat [-x86] [-x64] [--doc] This script will build the required configurations of Python and generate an installer layout in PCBuild/(win32|amd64)/en-us. Specify -x86 and/or -x64 to build for each platform. If neither is specified, both platforms will be built. Currently, both the debug and release versions of Python are required for the installer. Specify --doc to build the documentation (.chm) file. If the file is not available, it will simply be excluded from the installer. Ensure %PYTHON% and %SPHINXBUILD% are set when passing this option. You may also set %HTMLHELP% to the Html Help Compiler (hhc.exe), or put HHC on your PATH or in externals/. If WiX is not found on your system, it will be automatically downloaded and extracted to the externals/ directory. For an official release, the installer should be built with the Tools/msi/buildrelease.bat script: set PYTHON= set SPHINXBUILD= set PATH=; ;%PATH% buildrelease.bat [-x86] [-x64] [-D] [-B] [-o ] [-c ] Specify -x86 and/or -x64 to build for each platform. If neither is specified, both platforms will be built. Currently, both the debug and release versions of Python are required for the installer. Specify -D to skip rebuilding the documentation. The documentation is required for a release and the build will fail if it is not available. Specify -B to skip rebuilding Python. This is useful to only rebuild the installer layout after a previous call to buildrelease.bat. Specify -o to set an output directory. The installer layouts will be copied to platform-specific subdirectories of this path. Specify -c to choose a code-signing certificate to be used for all the signable binaries in Python as well as each file making up the installer. Official releases of Python must be signed. Ensure %PYTHON% and %SPHINXBUILD% are set when passing this option. You may also set %HTMLHELP% to the Html Help Compiler (hhc.exe), or put HHC on your PATH or in externals/. You will also need Mercurial (hg.exe) on your PATH. If WiX is not found on your system, it will be automatically downloaded and extracted to the externals/ directory. To manually build layouts of the installer, build one of the projects in the bundle folder. msbuild bundle\snapshot.wixproj msbuild bundle\releaseweb.wixproj msbuild bundle\releaselocal.wixproj msbuild bundle\full.wixproj snapshot.wixproj produces a test installer versioned based on the date. releaseweb.wixproj produces a release installer that does not embed any of the layout. releaselocal.wixproj produces a release installer that embeds the files required for a default installation. full.wixproj produces a test installer that embeds the entire layout. The following properties may be passed when building these projects. /p:BuildForRelease=(true|false) When true, adds extra verification to ensure a complete installer is produced. For example, binutils is required when building for a release to generate MinGW-compatible libraries, and the build will be aborted if this fails. Defaults to false. /p:ReleaseUri=(any URI) Used to generate unique IDs for the installers to allow side-by-side installation. Forks of Python can use the same installer infrastructure by providing a unique URI for this property. It does not need to be an active internet address. Defaults to $(ComputerName). Official releases use http://www.python.org/(architecture name) /p:DownloadUrlBase=(any URI) Specifies the base of a URL where missing parts of the installer layout can be downloaded from. The build version and architecture will be appended to create the full address. If omitted, missing components will not be automatically downloaded. /p:DownloadUrl=(any URI) Specifies the full URL where missing parts of the installer layout can be downloaded from. Should normally include '{2}', which will be substituted for the filename. If omitted, missing components will not be automatically downloaded. If specified, this value overrides DownloadUrlBase. /p:SigningCertificate=(certificate name) Specifies the certificate to sign the installer layout with. If omitted, the layout will not be signed. /p:RebuildAll=(true|false) When true, rebuilds all of the MSIs making up the layout. Defaults to true. Modifying the Installer ======================= The code for the installer is divided into three main groups: packages, the bundle and the bootstrap application. Packages -------- Packages appear as subdirectories of Tools/msi (other than the bundle/ directory). The project file is a .wixproj and the build output is a single MSI and any number of CAB files. Packages are built with the WiX Toolset. A package is the smallest element that may be independently installed or uninstalled (as used in this installer). For example, the test suite has its own package, as users can choose to add or remove it after the initial installation. Optional components spanning multiple packages, such as debug symbols, are represented as features within packages. These features are managed by the bootstrap application, rather than by the MSI (as is normal for single-MSI installers). The package references in package groups must have EnableFeatureSelection="yes", despite the warnings in the WiX documentation for this attribute. All the files installed by a single package should be related, though some packages may not install any files. For example, the pip package executes the ensurepip package, but does not add or remove any of its own files. (It is represented as a package because of its installed/uninstalled nature, as opposed to the "precompile standard library" option, for example.) Dependencies between packages are handled by the bundle, but packages should detect when dependencies are missing and raise an error. Packages may create multiple CAB files to minimise downloads. A CAB is the smallest unit of download, so by separating debug symbols into a separate CAB (for example), it will not be downloaded unless the symbols are being installed. Packages that include a lot of files may use an InstallFiles element in the .wixproj file to generate sources. See lib/lib.wixproj for an example, and msi.targets and csv_to_wxs.py for the implementation. This element is also responsible for generating the code for cleaning up and removing __pycache__ folders in any directory containing .py files. All packages are built with the Tools/msi/common.wxs file, and so any directory or property in this file may be referenced. Of particular interest: REGISTRYKEY (property) The registry key for the current installation. InstallDirectory (directory) The root install directory for the current installation. Subdirectories are also specified in this file (DLLs, Lib, etc.) MenuDir (directory) The Start Menu folder for the current installation. UpgradeTable (property) Every package should reference this property to include upgrade information. The .wxl_template file is specially handled by the build system for this project to perform {{substitutions}} as defined in msi.targets. They should be included in projects as items, where .wxl files are normally included as items. Bundle ------ The bundle is compiled to the main EXE entry point that for most users will represent the Python installer. It is built from Tools/msi/bundle with packages references in Tools/msi/bundle/packagegroups. Build logic for the bundle is in bundle.targets, but should be invoked through one of the .wixproj files as described in Building the Installer. The UI is separated between Default.thm (UI layout), Default.wxl (strings), bundle.wxs (properties) and the bootstrap application. Bundle.wxs also contains the chain, which is the list of packages to install and the order they should be installed in. These refer to named package groups in bundle/packagegroups. Each package group specifies one or more packages to install. Most packages require two separate entries to support both per-user and all-users installations. Because these reuse the same package, it does not increase the overall size of the package. Package groups refer to payload groups, which allow better control over embedding and downloading files than the default settings. Whether files are embedded and where they are downloaded from depends on settings created by the project files. Package references can include install conditions that determine when to install the package. When a package is a dependency for others, the condition should be crafted to ensure it is installed. MSI packages are installed or uninstalled based on their current state and the install condition. This makes them most suitable for features that are clearly present or absent from the user's machine. EXE packages are executed based on a customisable condition that can be omitted. This makes them suitable for pre- or post-install tasks that need to run regardless of whether features have been added or removed. Bootstrap Application --------------------- The bootstrap application is a C++ application that controls the UI and installation. While it does not directly compile into the main EXE of the installer, it forms the main active component. Most of the installation functionality is provided by WiX, and so the bootstrap application is predominantly responsible for the code behind the UI that is defined in the Default.thm file. The bootstrap application code is in bundle/bootstrap and is built automatically when building the bundle. Apart from UI, the bootstrap application contains the logic to select features for packages marked with EnableFeatureSelection="yes". These features must be hard-coded into the OnPlanMsiFeature() function by the ids of the feature and optionally the package. Installation Layout =================== There are two installation layouts for Python on Windows, with the only differences being supporting files. A layout is selected implicitly based on whether the install is for all users of the machine or just for the user performing the installation. The default installation location when installing for all users is "%ProgramFiles%\Python 3.X" for the 64-bit interpreter and "%ProgramFiles(x86)%\Python 3.X" for the 32-bit interpreter. (Note that the latter path is equivalent to "%ProgramFiles%\Python 3.X" when running a 32-bit version of Windows.) This location requires administrative privileges to install or later modify the installation. The default installation location when installing for the current user is "%LocalAppData%\Programs\Python\Python3X" for the 64-bit interpreter and "%LocalAppData%\Programs\Python\Python3X-32" for the 32-bit interpreter. Only the current user can access this location. This provides a suitable level of protection against malicious modification of Python's files. Within this install directory is the following approximate layout: .\python[w].exe The core executable files .\DLLs Stdlib extensions (*.pyd) and dependencies .\Doc Documentation (*.chm) .\include Development headers (*.h) .\Lib Standard library .\Lib\test Test suite .\libs Development libraries (*.lib) .\Scripts Launcher scripts (*.exe, *.py) .\tcl Tcl dependencies (*.dll, *.tcl and others) .\Tools Tool scripts (*.py) When installed for all users, the following files are installed to either "%SystemRoot%\System32" or "%SystemRoot%\SysWOW64" as appropriate. For the current user, they are installed in the Python install directory. .\python3x.dll The core interpreter .\python3.dll The stable ABI reference .\appcrt140.dll Microsoft Visual C Runtime .\desktopcrt140.dll Microsoft Visual C Runtime .\vcruntime140.dll Microsoft Visual C Runtime When installed for all users, the following files are installed to "%SystemRoot%" (typically "C:\Windows") to ensure they are always available on PATH. (See Launching Python below.) For the current user, they are installed in the Python install directory. .\py[w].exe PEP 397 launcher System Settings =============== On installation, registry keys are created so that other applications can locate and identify installations of Python. The locations of these keys vary based on the install type. For 64-bit interpreters installed for all users, the root key is: HKEY_LOCAL_MACHINE\Software\Python\PythonCore\3.X For 32-bit interpreters installed for all users on a 64-bit operating system, the root key is: HKEY_LOCAL_MACHINE\Software\Wow6432Node\Python\PythonCore\3.X-32 For 32-bit interpreters installed for all users on a 32-bit operating system, the root key is: HKEY_LOCAL_MACHINE\Software\Python\PythonCore\3.X-32 For 64-bit interpreters installed for the current user: HKEY_CURRENT_USER\Software\Python\PythonCore\3.X For 32-bit interpreters installed for the current user: HKEY_CURRENT_USER\Software\Python\PythonCore\3.X-32 When the core Python executables are installed, a key "InstallPath" is created within the root key with its default value set to the executable's install directory. Within this key, a key "InstallGroup" is created with its default value set to the product name "Python 3.X". When the Python standard library is installed, a key "PythonPath" is created within the root key with its default value set to the full path to the Lib folder followed by the path to the DLLs folder, separated by a semicolon. When the documentation is installed, a key "Help" is created within the root key, with a subkey "Main Python Documentation" with its default value set to the full path to the installed CHM file. The py.exe launcher is installed as part of a regular Python install, but using a separate mechanism that allows it to more easily span versions of Python. As a result, it has different root keys for its registry entries: When installed for all users on a 64-bit operating system, the launcher's root key is: HKEY_LOCAL_MACHINE\Software\Wow6432Node\Python\Launcher When installed for all users on a 32-bit operating system, the launcher's root key is: HKEY_LOCAL_MACHINE\Software\Python\Launcher When installed for the current user: HKEY_CURRENT_USER\Software\Python\Launcher When the launcher is installed, a key "InstallPath" is created within its root key with its default value set to the launcher's install directory. File associations are also created for .py, .pyw, .pyc and .pyo files. Launching Python ================ When a feature offering user entry points in the Start Menu is installed, a folder "Python 3.X" is created. Every shortcut should be created within this folder, and each shortcut should include the version and platform to allow users to identify the shortcut in a search results page. The core Python executables creates a shortcut "Python 3.X (32-bit)" or "Python 3.X (64-bit)" depending on the interpreter. The documentation creates a shortcut "Python 3.X 32-bit Manuals" or "Python 3.X 64-bit Manuals". The documentation is identical for all platforms, but the shortcuts need to be separate to avoid uninstallation conflicts. Installing IDLE creates a shortcut "IDLE (Python 3.X 32-bit)" or "IDLE (Python 3.X 64-bit)" depending on the interpreter. For users who often launch Python from a Command Prompt, an option is provided to add the directory containing python.exe to the user or system PATH variable. If the option is selected, the install directory and the Scripts directory will be added at the start of the system PATH for an all users install and the user PATH for a per-user install. When the user only has one version of Python installed, this will behave as expected. However, because Windows searches the system PATH before the user PATH, users cannot override a system-wide installation of Python on their PATH. Further, because the installer can only prepend to the path, later installations of Python will take precedence over earlier installations, regardless of interpreter version. Because it is not possible to automatically create a sensible PATH configuration, users are recommended to use the py.exe launcher and manually modify their PATH variable to add Scripts directories in their preferred order. System-wide installations of Python should consider not modifying PATH, or using an alternative technology to modify their users' PATH variables. The py.exe launcher is recommended because it uses a consistent and sensible search order for Python installations. User installations are preferred over system-wide installs, and later versions are preferred regardless of installation order (with the exception that py.exe currently prefers 2.x versions over 3.x versions without the -3 command line argument). For both 32-bit and 64-bit interpreters, the 32-bit version of the launcher is installed. This ensures that the search order is always consistent (as the 64-bit launcher is subtly different from the 32-bit launcher) and also avoids the need to install it multiple times. Future versions of Python will upgrade the launcher in-place, using Windows Installer's upgrade functionality to avoid conflicts with earlier installed versions. When installed, file associations are created for .py, .pyc and .pyo files to launch with py.exe and .pyw files to launch with pyw.exe. This makes Python files respect shebang lines by default and also avoids conflicts between multiple Python installations. Repair, Modify and Uninstall ============================ After installation, Python may be modified, repaired or uninstalled by running the original EXE again or via the Programs and Features applet (formerly known as Add or Remove Programs). Modifications allow features to be added or removed. The install directory and kind (all users/single user) cannot be modified. Because Windows Installer caches installation packages, removing features will not require internet access unless the package cache has been corrupted or deleted. Adding features that were not previously installed and are not embedded or otherwise available will require internet access. Repairing will rerun the installation for all currently installed features, restoring files and registry keys that have been modified or removed. This operation generally will not redownload any files unless the cached packages have been corrupted or deleted. Removing Python will clean up all the files and registry keys that were created by the installer, as well as __pycache__ folders that are explicitly handled by the installer. Python packages installed later using a tool like pip will not be removed. Some components may be installed by other installers (such as the MSVCRT) and these will not be removed if another product has a dependency on them.