Installation Guide

Complete instructions for installing and building CPython on all platforms

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

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

Fedora/RHEL/CentOS

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

macOS

# 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

1. 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
   
2. Configure

   Run the configure script:

   ./configure
   

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

3. Build

   Compile CPython:

   make -j$(nproc)
   

   The -j flag enables parallel compilation for faster builds.

4. Test

   Run the test suite to verify the build:

   make test
   

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

5. 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:

Installation Location

# 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:

1. Builds an instrumented version
2. Runs training workload
3. Rebuilds with optimization data

The optimized build process:

1. Initial Build

   Builds an instrumented interpreter with profiling code embedded

2. Profile Collection

   Runs benchmark suite to collect execution profile data

3. 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

1. Install Visual Studio

   Install Visual Studio 2017 or later with:

   • Python workload
   • Python native development component
2. Optional: Install Python

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

Visual Studio Build

1. Get Source

   Clone the repository or download source archive:

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

   Run the build script from PCbuild directory:

   cd PCbuild
   build.bat
   

   This builds 64-bit Release configuration by default.

3. Test

   Run the test suite:

   rt.bat -q
   

Build Options

Platform 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:

1. PGInstrument build - Creates instrumented binaries
2. Runs training workload
3. 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):

Unix/Linux (.bashrc or .zshrc)

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

FreeBSD

# 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:

1. 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
   
2. 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 found

Solution: Install build tools:

# Ubuntu/Debian
sudo apt install build-essential

# macOS
xcode-select --install

OpenSSL Issues

Error: Could not build the ssl module

Solution: 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 test

Solution:

• 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 install

Solution: 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 errors

Solution: 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