Installation Guide

This comprehensive guide covers installing CPython from pre-built binaries or building from source on all supported platforms. Whether you’re setting up a development environment or deploying to production, this guide has you covered.

Installation Options

Unix/Linux

Build from source with configure and make

macOS

Download installer or build with Xcode

Windows

Visual Studio build or pre-built installer

Building from Source (Unix/Linux/macOS)

Building CPython from source gives you full control over features and optimizations.

Prerequisites

Ubuntu/Debian
Fedora/RHEL/CentOS
macOS

sudo apt update
sudo apt install -y build-essential gdb lcov pkg-config \
      libbz2-dev libffi-dev libgdbm-dev libgdbm-compat-dev liblzma-dev \
      libncurses5-dev libreadline6-dev libsqlite3-dev libssl-dev \
      lzma lzma-dev tk-dev uuid-dev zlib1g-dev

sudo dnf install -y gcc gcc-c++ make pkgconfig \
      bzip2-devel gdbm-devel libffi-devel libnsl2-devel \
      libuuid-devel ncurses-devel openssl-devel \
      readline-devel sqlite-devel tk-devel xz-devel zlib-devel

# Install Xcode Command Line Tools
xcode-select --install

# Install Homebrew dependencies (optional but recommended)
brew install openssl readline sqlite3 xz zlib tcl-tk

For detailed platform-specific dependencies, see the Developer’s Guide.

Standard Build

Get the Source

Download from GitHub or python.org:

# From GitHub (development version)
git clone https://github.com/python/cpython.git
cd cpython

# Or download a release
wget https://www.python.org/ftp/python/3.15.0/Python-3.15.0.tar.xz
tar -xf Python-3.15.0.tar.xz
cd Python-3.15.0

Configure

Run the configure script:

./configure

This will detect your system and set up the build environment.

Build

Compile CPython:

make -j$(nproc)

The -j flag enables parallel compilation for faster builds.

Test

Run the test suite to verify the build:

make test

Some tests may be skipped due to missing optional dependencies. This is normal.

Install

Install Python system-wide:

sudo make install

This installs Python as python3.

Build Configuration Options

The configure script accepts many options to customize your build:

# Install to custom directory
./configure --prefix=/usr/local

# Install to user directory
./configure --prefix=$HOME/.local

# Specify separate directories
./configure --prefix=/usr/local --exec-prefix=/usr/local

Run ./configure --help to see all available options.

Optimized Build (PGO + LTO)

For maximum performance, use Profile-Guided Optimization (PGO) and Link-Time Optimization (LTO):

./configure --enable-optimizations
make -j$(nproc)
make test
sudo make install

PGO builds take significantly longer (2-3x) because the build process:

Builds an instrumented version
Runs training workload
Rebuilds with optimization data

The optimized build process:

Initial Build

Builds an instrumented interpreter with profiling code embedded

Profile Collection

Runs benchmark suite to collect execution profile data

Optimized Build

Rebuilds Python using profile data to optimize hot code paths

Alternative Install (Multiple Versions)

To install alongside existing Python versions without overwriting:

# Use altinstall instead of install
sudo make altinstall

This installs Python as python3.15 instead of python3, allowing multiple versions to coexist.

For example, you can have python3.14, python3.15, and python3 (symlink to default) all installed simultaneously.

Out-of-Tree Build

Build in a separate directory to keep source tree clean:

# Create build directory
mkdir build-release
cd build-release

# Configure from build directory
../configure --enable-optimizations
make -j$(nproc)
make test
sudo make install

Useful for testing different configurations:

mkdir debug && cd debug && ../configure --with-pydebug
mkdir release && cd release && ../configure --enable-optimizations

Building on macOS

macOS builds require special considerations for framework builds and universal binaries.

Standard macOS Build

# Install dependencies
brew install openssl readline sqlite3 xz zlib tcl-tk

# Configure with Homebrew libraries
./configure \
    --with-openssl=$(brew --prefix openssl) \
    --enable-optimizations
    
make -j$(sysctl -n hw.ncpu)
make test
sudo make install

Framework Build

For native macOS app integration:

./configure \
    --enable-framework=/Library/Frameworks \
    --with-openssl=$(brew --prefix openssl) \
    --enable-optimizations
    
make
sudo make install

Framework builds integrate better with macOS applications and IDEs but are not required for command-line use.

Universal Binary (Apple Silicon)

To build for both Intel and Apple Silicon:

./configure \
    --enable-universalsdk \
    --with-universal-archs=universal2
    
make
sudo make install

For more details, see Mac/README.rst in the source tree.

Building on Windows

Windows builds use Microsoft Visual Studio or Clang.

Prerequisites

Install Visual Studio

Install Visual Studio 2017 or later with:

Python workload
Python native development component

Optional: Install Python

Optionally install Python 3.10+ (used by build scripts if available)

Visual Studio Build

Get Source

Clone the repository or download source archive:

git clone https://github.com/python/cpython.git
cd cpython

Build

Run the build script from PCbuild directory:

cd PCbuild
build.bat

This builds 64-bit Release configuration by default.

Test

Run the test suite:

rt.bat -q

Build Options

# Build 32-bit
build.bat -p Win32

# Build 64-bit (default)
build.bat -p x64

# Build ARM64
build.bat -p ARM64

Profile-Guided Optimization (Windows)

For maximum performance on Windows:

cd PCbuild
build.bat --pgo

This performs:

PGInstrument build - Creates instrumented binaries
Runs training workload
PGUpdate build - Creates optimized binaries using profile data

PGO requires Premium Edition of Visual Studio. Community Edition also works for most scenarios.

Using Clang on Windows

To build with Clang/LLVM:

build.bat "/p:PlatformToolset=ClangCL"

For specific Clang version:

build.bat --pgo ^
    "/p:PlatformToolset=ClangCL" ^
    "/p:LLVMInstallDir=C:\Program Files\LLVM" ^
    "/p:LLVMToolsVersion=18"

Building Installer

To create Windows installer packages:

cd Tools\msi
buildrelease.bat

See Tools/msi/README.txt for details.

Post-Installation

Verify Installation

# Check version
python3 --version

# Check installation paths
python3 -c "import sys; print(sys.executable)"
python3 -c "import sys; print(sys.prefix)"

# Test basic functionality
python3 -c "print('Hello from CPython!')"

Set Up Environment

Add Python to your PATH (if not already done):

export PATH="/usr/local/bin:$PATH"
export PYTHONPATH="/usr/local/lib/python3.15/site-packages"

Install pip and setuptools

If pip is not included, bootstrap it:

python3 -m ensurepip --upgrade
python3 -m pip install --upgrade pip setuptools

Platform-Specific Notes

Linux Distributions

Ubuntu/Debian

# Install from apt (easier but older version)
sudo apt install python3 python3-pip python3-venv

# Or build from source for latest version
./configure --enable-optimizations --with-lto
make -j$(nproc)
sudo make altinstall

Fedora/RHEL/CentOS

# Install from dnf
sudo dnf install python3 python3-pip python3-devel

# Build from source
./configure --enable-optimizations
make -j$(nproc)
sudo make altinstall

Arch Linux

# Install from pacman
sudo pacman -S python python-pip

# Build from AUR for development version
yay -S python-git

FreeBSD and OpenBSD

# Install package
pkg install python3

# Or build from ports
cd /usr/ports/lang/python315
make install clean

Custom OpenSSL

To use a custom OpenSSL installation:

Download and Build OpenSSL

curl -O https://www.openssl.org/source/openssl-3.1.0.tar.gz
tar xzf openssl-3.1.0.tar.gz
cd openssl-3.1.0

./config \
    --prefix=/usr/local/custom-openssl \
    --libdir=lib \
    --openssldir=/etc/ssl
    
make -j$(nproc)
sudo make install_sw

Build Python with Custom OpenSSL

cd cpython
./configure \
    --with-openssl=/usr/local/custom-openssl \
    --with-openssl-rpath=auto
    
make -j$(nproc)
sudo make install

Patch releases of OpenSSL have backward-compatible ABI. You can update OpenSSL without recompiling Python.

Troubleshooting

Common Build Issues

Missing Dependencies

Error: configure: error: no acceptable C compiler foundSolution: Install build tools:

# Ubuntu/Debian
sudo apt install build-essential

# macOS
xcode-select --install

OpenSSL Issues

Error: Could not build the ssl moduleSolution: Install OpenSSL development files:

# Ubuntu/Debian
sudo apt install libssl-dev

# Fedora
sudo dnf install openssl-devel

# macOS
./configure --with-openssl=$(brew --prefix openssl)

Test Failures

Error: Some tests fail during make testSolution:

Check if only optional feature tests are failing
Review test output for actual errors vs. skipped tests
File a bug report if genuine test failures occur

# Run specific test in verbose mode
./python -m test -v test_os

Permission Denied

Error: Permission denied during make installSolution: Either use sudo or install to user directory:

# Option 1: Use sudo
sudo make install

# Option 2: User installation
./configure --prefix=$HOME/.local
make install

Out of Memory

Error: Compilation fails with memory errorsSolution: Reduce parallel jobs:

# Use fewer parallel jobs
make -j2

# Or single-threaded
make

Clean Build

If you encounter persistent issues, try a clean build:

# Clean previous build
make clean

# Or complete clean (removes all generated files)
make distclean

# Reconfigure and rebuild
./configure [options]
make

Windows-Specific Issues

Visual Studio Not Found

Run the build from “Developer Command Prompt for VS” or ensure Visual Studio is properly installed with C++ tools.

Python Not Found

Install Python 3.10+ or let build.bat download Python via NuGet automatically.

Performance Tuning

Recommended Build Flags

For production deployment:

./configure \
    --enable-optimizations \
    --with-lto \
    --enable-ipv6 \
    --with-system-expat \
    --with-system-ffi \
    --with-computed-gotos \
    --enable-loadable-sqlite-extensions

Memory Allocator

For better memory performance:

# Use mimalloc
./configure --with-mimalloc

# Or use jemalloc
./configure --with-system-libmpdec
export LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so

Next Steps

Quick Start

Start writing Python code immediately

Python Tutorial

Learn Python language fundamentals

Developer Guide

Contributing to CPython development

C API Reference

Extend Python with C/C++

Additional Resources

Build Dependencies: devguide.python.org/setup-building
Mac Build Instructions: Mac/README.rst
Windows Build Instructions: PCbuild/readme.txt
Source Downloads: python.org/downloads/source
GitHub Repository: github.com/python/cpython

Getting Started

Tutorial

Language Reference

How-To Guides

​Installation Options

Unix/Linux

macOS

Windows

​Building from Source (Unix/Linux/macOS)

​Prerequisites

​Standard Build

​Build Configuration Options

​Optimized Build (PGO + LTO)

​Alternative Install (Multiple Versions)

​Out-of-Tree Build

​Building on macOS

​Standard macOS Build

​Framework Build

​Universal Binary (Apple Silicon)

​Building on Windows

​Prerequisites

​Visual Studio Build

​Build Options

​Profile-Guided Optimization (Windows)

​Using Clang on Windows

​Building Installer

​Post-Installation

​Verify Installation

​Set Up Environment

​Install pip and setuptools

​Platform-Specific Notes

​Linux Distributions

​FreeBSD and OpenBSD

​Custom OpenSSL

​Troubleshooting

​Common Build Issues

​Clean Build

​Windows-Specific Issues

​Performance Tuning

​Recommended Build Flags

​Memory Allocator

​Next Steps

Quick Start

Python Tutorial

Developer Guide

C API Reference

​Additional Resources

Build docs developers (and LLMs) love

Installation Options

Building from Source (Unix/Linux/macOS)

Prerequisites

Standard Build

Build Configuration Options

Optimized Build (PGO + LTO)

Alternative Install (Multiple Versions)

Out-of-Tree Build

Building on macOS

Standard macOS Build

Framework Build

Universal Binary (Apple Silicon)

Building on Windows

Prerequisites

Visual Studio Build

Build Options

Profile-Guided Optimization (Windows)

Using Clang on Windows

Building Installer

Post-Installation

Verify Installation

Set Up Environment

Install pip and setuptools

Platform-Specific Notes

Linux Distributions

FreeBSD and OpenBSD

Custom OpenSSL

Troubleshooting

Common Build Issues

Clean Build

Windows-Specific Issues

Performance Tuning

Recommended Build Flags

Memory Allocator

Next Steps

Additional Resources