Introduction

Many Python packages (numpy, cryptography, psycopg2, Pillow) include C extensions that must be compiled during installation. When the Python development headers or system build tools are missing, pip fails with errors like "Python.h: No such file or directory" or "command gcc failed".

This is especially common on minimal Linux installations, Docker containers, and fresh macOS setups with only the Python runtime installed.

Symptoms

  • pip install fails with "fatal error: Python.h: No such file or directory"
  • Build error shows "x86_64-linux-gnu-gcc failed with exit status 1"
  • Error occurs specifically when compiling packages with native C/C++ extensions

Common Causes

  • Python development headers (python3-dev) not installed on the system
  • C compiler (gcc, clang) or build essentials missing
  • Missing library-specific development headers (libffi-dev, openssl-dev, etc.)

Step-by-Step Fix

  1. 1.Install Python development headers on Debian/Ubuntu: Install the python3-dev package and build essentials.
  2. 2.```bash
  3. 3.sudo apt-get update
  4. 4.sudo apt-get install -y python3-dev python3-pip build-essential

# For specific Python version: sudo apt-get install -y python3.11-dev

# Then retry: pip install numpy ```

  1. 1.Install development packages on RHEL/CentOS/Fedora: Use yum or dnf for Red Hat family systems.
  2. 2.```bash
  3. 3.# RHEL/CentOS:
  4. 4.sudo yum install -y python3-devel gcc gcc-c++ make

# Fedora: sudo dnf install -y python3-devel gcc gcc-c++ make

# Then retry: pip install numpy ```

  1. 1.Install Xcode command line tools on macOS: macOS needs Xcode tools for C compilation.
  2. 2.```bash
  3. 3.# Install Xcode command line tools:
  4. 4.xcode-select --install

# If already installed but broken, reset: sudo xcode-select --reset ```

  1. 1.Use pre-built wheels to avoid compilation: Many packages provide pre-compiled binary wheels.
  2. 2.```bash
  3. 3.# Upgrade pip to get latest wheel support:
  4. 4.pip install --upgrade pip

# Install with binary-only flag: pip install --only-binary :all: numpy cryptography psycopg2-binary

# Use binary package variants where available: pip install psycopg2-binary # Instead of psycopg2 ```

Prevention

  • Include build dependencies in Dockerfiles and provisioning scripts
  • Use --only-binary :all: in requirements.txt to enforce wheel-only installs
  • Use manylinux/musllinux compliant wheels for cross-platform compatibility
  • Prefer binary package variants (psycopg2-binary, mysqlclient pre-built)