Skip to main content
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

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.
Messages about skipped tests for optional features are normal:
test_ssl skipped -- No module named '_ssl'
Only worry about actual failures or tracebacks.
If you’re seeing weird behavior:
make clean
./configure
make
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

​
Additional Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us