Building CPython from Source

Learn how to build CPython from source code

This guide covers building CPython from source code for development purposes. Building from source allows you to test changes, debug issues, and contribute to CPython development.

Basic Build Process

1. Configure the build

   From the top-level directory:

   ./configure
   

   This prepares the build system for your platform.

2. Build CPython

   make
   

   This compiles the Python interpreter and standard library.

3. Test the build

   make test
   

   This runs the test suite to verify your build.

4. Install (optional)

   sudo make install
   

   This installs Python as python3. For development, you typically don’t need to install.

The executable is called python.exe on macOS case-insensitive file systems and Cygwin; elsewhere it’s just python.

Development Builds

Debug Build

For development work, use a debug build with additional checks:

./configure --with-pydebug
make

A debug build:

• Enables assertions and extra debugging code
• Includes reference count tracking
• Adds memory debugging features
• Makes debugging with gdb easier

Out-of-Tree Build

To keep your source directory clean, use an out-of-tree build:

mkdir debug
cd debug
../configure --with-pydebug
make

If you’ve already built in the top-level directory, run make clean there first to avoid conflicts.

Build Options

Optimized Build

For performance testing or benchmarking:

./configure --enable-optimizations
make

This enables:

• Profile Guided Optimization (PGO): Optimizes based on runtime profiling
• Link Time Optimization (LTO): Cross-module optimization (on supported platforms)

Optimized builds take significantly longer due to the profiling step. Use them only when performance matters.

Common Configure Options

# View all options
./configure --help

# Debug build with additional checks
./configure --with-pydebug

# Optimized build
./configure --enable-optimizations

# Link Time Optimization
./configure --with-lto

# Specify OpenSSL location (macOS)
./configure --with-openssl=/usr/local/opt/openssl

# Install to custom prefix
./configure --prefix=/opt/python3.15

Profile Guided Optimization (PGO)

When you use --enable-optimizations or run make profile-opt, the build process:

1. Clean

   Removes temporary files from previous builds.

2. Build instrumented interpreter

   Creates an instrumented version with profiling code embedded.

3. Run training workload

   Executes the test suite to collect profiling data. Output is suppressed during this step.

4. Build optimized interpreter

   Builds the final interpreter using the profiling data for optimization.

Platform-Specific Builds

macOS Framework Build

macOS has special framework build options:

./configure --enable-framework
make

See Mac/README.rst for details on:

• Framework builds
• Universal builds
• Code signing requirements

Windows

Windows uses a different build system:

cd PCbuild
build.bat

See PCbuild/readme.txt for:

• Visual Studio requirements
• Build configurations
• Creating Windows installers

Build Targets

# Standard build
make

# Run tests
make test

# Run tests with resource usage enabled
make buildbottest

# Profile-guided optimization
make profile-opt

# Clean build artifacts
make clean

# Remove all generated files
make distclean

# Install multiple versions side-by-side
make altinstall

Parallel Builds

Speed up compilation with parallel jobs:

# Use all CPU cores
make -j

# Use specific number of jobs
make -j4

Installing Multiple Versions

To install multiple Python versions using the same prefix:

1. Decide on primary version

   Choose which version will be your “primary” Python (e.g., 3.15).

2. Install primary version

   # In Python 3.15 directory
   ./configure --prefix=/usr/local
   make
   make install
   
3. Install other versions with altinstall

   # In Python 3.14 directory
   ./configure --prefix=/usr/local
   make
   make altinstall
   

make altinstall prevents overwriting the python3 symlink.

Troubleshooting

Build fails with missing dependencies

Some standard library modules require external libraries. The build will succeed but those modules will be unavailable. Check:

# After build, check for missing modules
./python -c "import ssl"  # Test SSL
./python -c "import tkinter"  # Test Tk

Install missing dependencies and rebuild.

make test fails on optional modules

Messages about skipped tests for optional features are normal:

test_ssl skipped -- No module named '_ssl'

Only worry about actual failures or tracebacks.

Stale build artifacts

If you’re seeing weird behavior:

make clean
./configure
make

Permission errors during install

For system-wide installation:

sudo make install

For development, consider installing to a user directory:

./configure --prefix=$HOME/.local
make
make install

Verifying Your Build

After building, verify it works:

# Run the interpreter
./python

# Check version
./python --version

# Test import
./python -c "import sys; print(sys.version)"

# Run a simple test
./python -m test.test_grammar

Next Steps

• Run the test suite
• Learn the development workflow
• Understand code style guidelines

Additional Resources

• CPython Developer Guide
• Special Build Types (Misc/SpecialBuilds.txt)
• GitHub Actions CI
• Azure Pipelines CI