Install pre-commit as a Git hook¶

To make sure your code is linted correctly, we recommend setting uppre-commit as a Git hook:

$pre-commitinstall--allow-missing-configpre-commit installed at .git/hooks/pre-commit

Now pre-commit will run automatically ongitcommit.

Unix¶

The core CPython interpreter only needs a C compiler to be built,however, some of the extension modules will need development headersfor additional libraries (such as thezlib library for compression).Depending on what you intend to work on, you might need to install theseadditional requirements so that the compiled interpreter supports thedesired features.

If you want to install these optional dependencies, consult theInstall dependencies section below.

If you don’t need to install them, the basic steps for building Pythonfor development is to configure it and then compile it.

Configuration is typically:

$./configure--with-pydebug

More flags are available toconfigure, but this is the minimum you shoulddo to get a pydebug build of CPython.

Onceconfigure is done, you can then compile CPython with:

$make-s-j$(nproc)

This will build CPython with only warnings and errors being printed tostderr. The-j argument means thatmake will concurrently runtasks, limiting the number of parallel jobs to the number of CPU cores in yourcomputer. You can adjust the number passed to the-j flag to changethe limit on parallel jobs, which can trade RAM usage versus compilation time.

At the end of the build you should see a success message, followedby a list of extension modules that haven’t been built because theirdependencies were missing:

The necessary bits to build these optional modules were not found:_gdbmTo find the necessary bits, look in configure.ac and config.log.Checked 106 modules (31 built-in, 74 shared, 0 n/a on macosx-13.4-arm64, 0 disabled, 1 missing, 0 failed on import)

If the build failed and you are using a C89 or C99-compliant compiler,please open a bug report on theissue tracker.

If you decide toInstall dependencies, you will need to re-run bothconfigure andmake.

Once CPython is done building you will then have a working buildthat can be run in-place;./python on most machines (and what is used inall examples),./python.exe wherever a case-insensitive filesystem is used(for example, on macOS by default), in order to avoid conflicts with thePythondirectory. There is normally no need to install your built copyof Python! The interpreter will realize where it is being run fromand thus use the files found in the working copy. If you are worriedyou might accidentally install your working copy build, you can add--prefix=/tmp/python to the configuration step. When running from yourworking directory, it is best to avoid using the--enable-shared flagtoconfigure; unless you are very careful, you may accidentally runwith code from an older, installed shared Python library rather than fromthe interpreter you just built.

$./configure--enable-optimizations--with-lto

Windows¶

For a concise step by step summary of building Python on Windows,you can readVictor Stinner’s guide.

All supported versions of Python can be builtusing Microsoft Visual Studio 2017 or later.You can download and use any of the free or paid versions ofVisual Studio.

When installing it, select thePython development workloadand the optionalPython native development tools componentto obtain all of the necessary build tools.You can find Git for Windows on theIndividual components tabif you don’t already have it installed.

Your first build should use the command line to ensure any external dependenciesare downloaded:

PCbuild\build.bat -c Debug

The above command line build uses the-cDebug argumentto build in theDebug configuration,which enables checks and assertions helpful for developing Python.By default, it builds in theRelease configurationand for the 64-bitx64 platform rather than 32-bitWin32;use-c and-p to control build config and platform, respectively.

After this build succeeds, you can open thePCbuild\pcbuild.sln solutionin the Visual Studio IDE to continue development, if you prefer.When building in Visual Studio,make sure to select build settings that match what you used with the script(theDebug configuration and thex64 platform)from the dropdown menus in the toolbar.

You can run the build of Python you’ve compiled with:

PCbuild\amd64\python_d.exe

See thePCBuild readme for more details on what other software is necessaryand how to build.

WASI¶

WASI is a system interface standard forWebAssembly. Through a combination ofC compilers that can target WebAssembly andwasi-libc providingPOSIX-compatible shims for WASI, it’s possible for CPython to run on a WASIhost/runtime as aguest.

To build for WASI, you will need to cross-compile CPython. This requires a Ccompiler just like building forUnix as well as:

1. A C compiler that can target WebAssembly (for example,WASI SDK)

2. A WASI host/runtime (for example,Wasmtime)

All of this is provided in thedevcontainer. You canalso use what’s installed in the container as a reference of what versions ofthese tools are known to work.

Building for WASI requires doing a cross-build where you have abuild Pythonto help produce a WASI build of CPython (technically it’s a “host x host”cross-build because the build Python is also the target Python while the hostbuild is the WASI build). This means you effectively build CPython twice: onceto have a version of Python for the build system to use and another that’s thebuild you ultimately care about (that is, the build Python is not meant for use byyou directly, only the build system).

The easiest way to get a debug build of CPython for WASI is to use theTools/wasm/wasi.pybuild command (which should be run w/ a recent version ofPython you have installed on your machine):

$python3Tools/wasm/wasibuild--quiet----config-cache--with-pydebug

For Python 3.14 and earlier, useTools/wasm/wasi.py instead.

That single command will configure and build both the build Python and theWASI build incross-build/build andcross-build/wasm32-wasi,respectively.

You can also do each configuration and build step separately; the command aboveis a convenience wrapper around the following commands:

$pythonTools/wasm/wasiconfigure-build-python--quiet----config-cache--with-pydebug$pythonTools/wasm/wasimake-build-python--quiet$pythonTools/wasm/wasiconfigure-host--quiet----config-cache$pythonTools/wasm/wasimake-host--quiet

Running the separate commands afterwasi.pybuild is useful if you, for example, only want torun themake-host step after making code changes.

Once everything is complete, there will be across-build/wasm32-wasi/python.sh helper file which you can use to run thepython.wasm file (see the output from theconfigure-host subcommand):

$cross-build/wasm32-wasi/python.sh--version

You can also useMakefile targets and they will work as expected thanks totheHOSTRUNNER environment variable having been set to a similar value asused inpython.sh:

$make-Ccross-build/wasm32-wasitest

Emscripten¶

Emscripten is a complete open-source compiler toolchain. It compiles C/C++ codeintoWebAssembly/JavaScript executables, for use in JavaScript runtimes,including browsers and Node.js.

To build for Emscripten, you will need to cross-compile CPython. This requires aC compiler just like building forUnix as well as:

• The Emscripten compiler

• Node.js

The simplest way to install the Emscripten compiler is:

# Install Emscriptengitclonehttps://github.com/emscripten-core/emsdk./emsdk/emsdkinstall4.0.5./emsdk/emsdkactivate4.0.5source./emsdk/emsdk_env.sh

Updating the Emscripten compiler version often causes breakages. For the bestcompatibility, use the Emscripten version suggested in the cpython repository inTools/wasm/README.md.

Building for Emscripten requires doing a cross-build where you have abuildPython to help produce an Emscripten build of CPython. This means you buildCPython twice: once to have a version of Python for the build system to use andanother that’s the build you ultimately care about (that is, the build Python isnot meant for use by you directly, only the build system).

The easiest way to get a debug build of CPython for Emscripten is to use theTools/wasm/emscriptenbuild command (which should be run with a recentversion of Python you have installed on your machine):

python3Tools/wasm/emscriptenbuild--quiet----config-cache--with-pydebug

That single command will configure and build both the build Python and theEmscripten build incross-build/build andcross-build/wasm32-emscripten/build/python/, respectively.

You can also do each configuration and build step separately; the command aboveis a convenience wrapper around the following commands:

pythonTools/wasm/emscriptenconfigure-build-python--quiet----config-cache--with-pydebugpythonTools/wasm/emscriptenmake-build-python--quietpythonTools/wasm/emscriptenmake-libffi--quietpythonTools/wasm/emscriptenconfigure-host--quiet----config-cachepythonTools/wasm/emscriptenmake-host--quiet

Running the separate commands afteremscriptenbuild is useful if you, forexample, only want to run themake-host step after making code changes.

Once everything is complete, there will be across-build/wasm32-emscripten/build/python/python.sh helper file which youcan use to run thepython.mjs file:

cross-build/wasm32-emscripten/build/python/python.sh--version

You can also useMakefile targets and they will work as expected thanks totheHOSTRUNNER environment variable having been set to a similar value asused inpython.sh:

make-Ccross-build/wasm32-emscripten/build/python/test

Android¶

Build and test instructions for Android are maintained in the CPython repositoryatAndroid/README.md.

iOS¶

Compiling Python for iOS requires a macOS machine, on a recent version of macOS,running a recent version of Xcode. Apple expects developers to keep theiroperating systems and tools up-to-date; if your macOS version is more than onemajor release out of date, or your Xcode version is more than a couple of minorversions out of date, you’ll likely encounter difficulties. It is not possibleto compile for iOS using Windows or Linux as a build machine.

A complete build for Python on iOS requires compiling CPython four times: once formacOS; then once for each of the three underlying platforms used by iOS:

• An ARM64 device (an iPhone or iPad);

• An ARM64 simulator running on a recent macOS machine; and

• An x86_64 simulator running on older macOS machine.

The macOS build is required because building Python involves running some Pythoncode. On a normal desktop build of Python, you can compile a Python interpreterand then use that interpreter to run Python code. However, the binaries producedfor iOS won’t run on macOS, so you need to provide an external Pythoninterpreter. From the root of a CPython code checkout, run the following:

$./configure--prefix=$(pwd)/cross-build/macOS$make-j4all$makeinstall

This will build and install Python for macOS into thecross-build/macOSdirectory.

The CPython build system can compile a single platform at a time. It is possibletotest a single platform at a time; however, for distribution purposes, youmust compile all three, and merge the results. See theiOS READMEfor details on this merging process.

The following instructions will build CPython for iOS with all extensionsenabled, provided you have installed the build dependencies XZ, BZip2, OpenSSLand libFFI in subfolders of thecross-build folder. Seethe iOSsection on installing build dependencies for details onhow to obtain these dependencies. These dependencies are all strictly optional,however, including libFFI ishighly recommended, as it is required by thectypes module which is used on iOS to support accessing native system APIs.

$exportPATH="$(pwd)/iOS/Resources/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Library/Apple/usr/bin"$./configure\LIBLZMA_CFLAGS="-I$(pwd)/cross-build/iphoneos.arm64/xz/include"\LIBLZMA_LIBS="-L$(pwd)/cross-build/iphoneos.arm64/xz/lib -llzma"\BZIP2_CFLAGS="-I$(pwd)/cross-build/iphoneos.arm64/bzip2/include"\BZIP2_LIBS="-L$(pwd)/cross-build/iphoneos.arm64/bzip2/lib -lbz2"\LIBFFI_CFLAGS="-I$(pwd)/cross-build/iphoneos.arm64/libffi/include"\LIBFFI_LIBS="-L$(pwd)/cross-build/iphoneos.arm64/libffi/lib -lffi"\--with-openssl="$(pwd)/cross-build/iphoneos.arm64/openssl"\--host=arm64-apple-ios12.0\--build=arm64-apple-darwin\--with-build-python=$(pwd)/cross-build/macOS/bin/python3.13\--enable-framework$make-j4all$makeinstall

$exportPATH="$(pwd)/iOS/Resources/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Library/Apple/usr/bin"$./configure\LIBLZMA_CFLAGS="-I$(pwd)/cross-build/iphonesimulator.arm64/xz/include"\LIBLZMA_LIBS="-L$(pwd)/cross-build/iphonesimulator.arm64/xz/lib -llzma"\BZIP2_CFLAGS="-I$(pwd)/cross-build/iphonesimulator.arm64/bzip2/include"\BZIP2_LIBS="-L$(pwd)/cross-build/iphonesimulator.arm64/bzip2/lib -lbz2"\LIBFFI_CFLAGS="-I$(pwd)/cross-build/iphonesimulator.arm64/libffi/include"\LIBFFI_LIBS="-L$(pwd)/cross-build/iphonesimulator.arm64/libffi/lib -lffi"\--with-openssl="$(pwd)/cross-build/iphonesimulator.arm64/openssl"\--host=arm64-apple-ios12.0-simulator\--build=arm64-apple-darwin\--with-build-python=$(pwd)/cross-build/macOS/bin/python3.13\--enable-framework$make-j4all$makeinstall

$exportPATH="$(pwd)/iOS/Resources/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Library/Apple/usr/bin"$./configure\LIBLZMA_CFLAGS="-I$(pwd)/cross-build/iphonesimulator.x86_64/xz/include"\LIBLZMA_LIBS="-L$(pwd)/cross-build/iphonesimulator.x86_64/xz/lib -llzma"\BZIP2_CFLAGS="-I$(pwd)/cross-build/iphonesimulator.x86_64/bzip2/include"\BZIP2_LIBS="-L$(pwd)/cross-build/iphonesimulator.x86_64/bzip2/lib -lbz2"\LIBFFI_CFLAGS="-I$(pwd)/cross-build/iphonesimulator.x86_64/libffi/include"\LIBFFI_LIBS="-L$(pwd)/cross-build/iphonesimulator.x86_64/libffi/lib -lffi"\--with-openssl="$(pwd)/cross-build/iphonesimulator.x86_64/openssl"\--host=x86_64-apple-ios12.0-simulator\--build=arm64-apple-darwin\--with-build-python=$(pwd)/cross-build/macOS/bin/python3.13\--enable-framework$make-j4all$makeinstall

These instructions modify yourPATH before the build. As iOS and macOS sharea hardware architecture (ARM64), it is easy for a macOS ARM64 binary to beaccidentally linked into your iOS build. This is especially common when Homebrewis present on the build system. The most reliable way to avoid this problem isto remove any potential source of other libraries from yourPATH.

However, thePATH is not completely bare — it includes theiOS/Resources/bin folder. This folder contains a collection of scripts thatwrap the invocation of the Xcodexcrun tool, removing user- andversion-specific paths from the values encoded in thesysconfigmodule. Copies of these scripts are included in the final build products.

Once this build completes, theiOS/Frameworks folder will contain aPython.framework that can be used for testing.

To run the test suite on iOS, complete a build for asimulator platform,ensure the path modifications from the build are still in effect, and run:

$maketestios

The full test suite takes approximately 12 minutes to run on a 2022 M1 MacBookPro, plus a couple of extra minutes to build the testbed application and bootthe simulator. There will be an initial burst of console output while the Xcodetest project is compiled; however, while the test suite is running, there is noconsole output or progress. This is a side effect of how Xcode operates whenexecuted at the command line. You should see an iOS simulator appear during thetesting process; the simulator will booth to an iOS landing screen, the testbedapp will be installed, and then started. The screen of the simulator will beblack while the test suite is running. When the test suite completes, success orfailure will be reported at the command line. In the case of failure, you willsee the full log of CPython test suite output.

You can also run the test suite in Xcode itself. This is required if you want torun on a physical device; it is also the easiest approach if you need to run asingle test, or a subset of tests. See theiOS READMEfor details.

Avoid recreating auto-generated files¶

Under some circumstances you may encounter Python errors in scripts likeParser/asdl_c.py orPython/makeopcodetargets.py while runningmake.Python auto-generates some of its own code, and a full build from scratch needsto run the auto-generation scripts. However, this makes the Python build requirean already installed Python interpreter; this can also cause version mismatcheswhen trying to build an old (2.x) Python with a new (3.x) Python installed, orvice versa.

To overcome this problem, auto-generated files are also checked into theGit repository. So if you don’t touch the auto-generation scripts, there’sno real need to auto-generate anything.

What is GitHub Codespaces?¶

If you’d like to start contributing to CPython without needing to set up a localdeveloper environment, you can useGitHub Codespaces.Codespaces is a cloud-based development environment offered by GitHub thatallows developers to write, build, test, and debug code directly within theirweb browser or in Visual Studio Code (VS Code).

To help you get started, CPython contains adevcontainer folderwith a JSON configuration file that provides consistent and versioned codespaceconfigurations for all users of the project. It also contains a Dockerfile thatallows you to set up the same environment but locally in a Docker container ifyou’d prefer to use that directly.

Create a CPython codespace¶

Here are the basic steps needed to contribute a pull request using Codespaces.You first need to navigate to theCPython repo hosted on GitHub.

Then you will need to:

1. Press the, key to launch the codespace setup screen for the currentbranch (alternatively, click the greenCode button and choosethecodespaces tab and then press thegreenCreate codespace on main button).

2. A screen should appear that lets you know your codespace is being set up.(Note: Since the CPython devcontainer is provided, codespaces will use theconfiguration it specifies.)

3. Aweb version of VS Code will open inside your webbrowser, already linked up with your code and a terminal to the remotecodespace where CPython and its documentation have already been built.

4. Use the terminal with the usual Git commands to create a new branch, commitand push your changes once you’re ready!

If you close your repository and come back later you can always resume yourcodespace by navigating to the CPython repo, selecting the codespaces tab andselecting your most recent codespaces session. You should then be able to pickup from where you left off!

Use Codespaces locally¶

On the bottom left side of the codespace screen you will see a green or greysquare that saysCodespaces. You can click this for additionaloptions. If you prefer working in a locally installed copy of VS Code you canselect the optionOpeninVSCode. You will still be working on the remotecodespace instance, thus using the remote instance’s compute power. The computepower may be a much higher spec than your local machine which can be helpful.

Using the pre-built container image¶

Dev container imagesare available from theGitHub Container Registry (GHCR) account for the Python org.

To run the container and launch a Bash shell, run one of the following commandsin a clone of the CPython repository.

dockerrun-it--rm--volume$PWD:/workspace--workdir/workspaceghcr.io/python/devcontainer:latest

podmanrun-it--rm--volume$PWD:/workspace:Z--workdir/workspaceghcr.io/python/devcontainer:latest

Note that the container has read/write access to the working directory.You may want to use a separate clone of CPython, or runmakecleanto remove caches and build output generated for your host OS.

Building yourself¶

If you prefer, you can build the container image yourself. In a clone of thecpython-devcontainers repo,build the container and name itcpython-dev:

dockerbuilddevcontainer/--tagcpython-dev

(Substitutepodman fordocker if you use Podman.)

The same command will update any existingcpython-dev container.Run it again from time to time – especially if the container stopsworking for you.

To run the container and launch a Bash shell, run one of the following commandsin a clone of the CPython repository.

dockerrun-it--rm--volume$PWD:/workspace--workdir/workspacecpython-dev

podmanrun-it--rm--volume$PWD:/workspace:Z--workdir/workspacecpython-dev

The same caveats outlined above when running from a container image from GHCRalso apply here.