Getting started

This page covers building, running, and testing a development CPython on Unix-like systems. For platform-specific notes see Mac/README.rst and PCbuild/readme.txt.

Prerequisites

CPython needs a C compiler (gcc, clang, or MSVC), make, and a small set of system libraries. The full list of dev-mode dependencies for each major Linux distribution is in the devguide build setup page. Notable optional dependencies:

System library	Used by
OpenSSL	ssl, hashlib (Modules/_ssl.c)
zlib	zlib, gzip
libffi	ctypes (Modules/_ctypes/)
Tk/Tcl	tkinter (Modules/_tkinter.c)
ncurses	curses
GDBM, dbm	dbm.*
readline	interactive REPL
sqlite3	sqlite3 (Modules/_sqlite/)
expat	xml.parsers.expat (vendored under Modules/expat/)

A missing optional dependency is not fatal: the affected stdlib module is silently skipped during the build. After a build, python -c "import ssl" and import sqlite3 etc. are good smoke tests.

Cloning and building

The standard Unix flow is documented in README.rst:

git clone https://github.com/python/cpython.git
cd cpython
./configure --with-pydebug
make -j
./python -V

The most useful configure flags during development:

Flag	Purpose
--with-pydebug	Assertions, refcount tracing, extra type checks (this is what to use)
--enable-optimizations	PGO + (optionally) LTO; slow to build, only for releases / benchmarks
--with-lto	Enable LTO
--enable-experimental-jit	Build the copy-and-patch JIT (see JIT)
--enable-experimental-jit=interpreter	Use the uop interpreter without code generation (good for debugging)
--disable-gil	Free-threaded build (PEP 703)
--prefix=$HOME/cpython-build	Sandbox installs done with make altinstall

Out-of-tree builds work and are encouraged for trying multiple configurations:

mkdir build-debug && cd build-debug
../configure --with-pydebug
make -j

The Makefile is generated from Makefile.pre.in, which is itself driven by configure.ac. See Tooling for the regeneration story.

Running the in-tree interpreter

After make, the built binary is ./python (named ./python.exe on macOS case-insensitive filesystems and Cygwin). Some launchers worth knowing:

• ./python — runs without installing.
• make test — runs the standard test suite (a thin wrapper around python -m test).
• make buildbottest — like make test but with the -uall resource set, used by buildbots.
• make pythoninfo — prints a verbose info dump useful in bug reports.
• make clinic — regenerates Argument Clinic glue (see Tooling).
• make regen-all — regenerates all checked-in generated files (parser, bytecode tables, opcode IDs, ast, …).

Running tests

The CPython test suite is a custom harness (Lib/test/libregrtest/) on top of unittest:

./python -m test                    # run the full suite
./python -m test test_os test_json  # specific tests
./python -m test -j8 -uall          # 8 workers, all resource categories
./python -m test -v test_os         # verbose
./python -m test -W                 # re-run failures, useful for flaky tests

A failed test prints the exact command to re-run it. See Testing for more.

Installing alongside your system Python

./configure --prefix=$HOME/.local
make -j
make altinstall    # installs as python3.15, never overwrites python3

make altinstall is what you want any time you might already have a python3 on PATH. make install also creates a python3 symlink and is reserved for the primary installed version (see "Installing multiple versions" in README.rst).

Useful first reads

• README.rst — official top-level README
• InternalDocs/ — implementation reference (parser, compiler, GC, JIT, frames, …)
• https://devguide.python.org/ — the Python developer's guide (PR workflow, expert index, build dependencies)
• Patterns and conventions — coding style and recurring idioms