Introduction

Many Python packages include C extensions for performance (numpy, pandas, cryptography, psycopg2). When pip cannot find a pre-built wheel for your platform, it falls back to building from source. This requires a C compiler, Python development headers, and sometimes library-specific dependencies like OpenSSL headers. Missing any of these causes build failure.

Symptoms

  • fatal error: Python.h: No such file or directory
  • error: command 'gcc' failed: No such file or directory
  • clang: error: linker command failed with exit code 1
  • openssl/opensslv.h: No such file or directory
  • error: Microsoft Visual C++ 14.0 or greater is required

``` Building wheel for cryptography (pyproject.toml) ... error error: subprocess-exited-with-error

× Building wheel for cryptography failed note: This error originates from a subprocess cargo:rustc-link-search=native=/usr/lib cargo:rerun-if-env-changed=OPENSSL_NO_VENDOR running build_ext error: can't find Rust compiler ```

Common Causes

  • Missing system compiler (gcc, clang, MSVC)
  • No Python development headers installed
  • Missing library-specific dependencies (OpenSSL, libxml2, etc.)
  • No pre-built wheel available for your CPU architecture (ARM64, M1/M2)
  • Outdated pip version that does not support manylinux2014 wheels

Step-by-Step Fix

  1. 1.Install build tools on Ubuntu/Debian:
  2. 2.```bash
  3. 3.sudo apt update
  4. 4.sudo apt install -y build-essential python3-dev pkg-config
  5. 5.# For specific packages:
  6. 6.sudo apt install -y libssl-dev libffi-dev libxml2-dev libxslt1-dev
  7. 7.# For psycopg2:
  8. 8.sudo apt install -y libpq-dev
  9. 9.# For mysqlclient:
  10. 10.sudo apt install -y default-libmysqlclient-dev
  11. 11.`
  12. 12.Install build tools on CentOS/RHEL:
  13. 13.```bash
  14. 14.sudo yum groupinstall -y "Development Tools"
  15. 15.sudo yum install -y python3-devel openssl-devel libffi-devel
  16. 16.# For psycopg2:
  17. 17.sudo yum install -y postgresql-devel
  18. 18.`
  19. 19.Install build tools on macOS:
  20. 20.```bash
  21. 21.xcode-select --install
  22. 22.brew install openssl libffi pkg-config

# Tell pip where to find OpenSSL export LDFLAGS="-L/opt/homebrew/opt/openssl@3/lib" export CPPFLAGS="-I/opt/homebrew/opt/openssl@3/include" pip install cryptography ```

  1. 1.Install build tools on Windows:
  2. 2.```bash
  3. 3.# Install Visual Studio Build Tools
  4. 4.# Download from: https://visualstudio.microsoft.com/visual-cpp-build-tools/
  5. 5.# Select "Desktop development with C++" workload

# Or use winget winget install Microsoft.VisualStudio.2022.BuildTools --override "--passive --add Microsoft.VisualStudio.Workload.VCTools" ```

  1. 1.Force pre-built wheel installation to avoid compilation:
  2. 2.```bash
  3. 3.pip install --only-binary :all: cryptography pandas numpy
  4. 4.# Fails if no wheel available, avoiding build entirely

# Or use a platform with available wheels pip install --platform manylinux2014_x86_64 --python-version 311 --only-binary :all: cryptography ```

  1. 1.Upgrade pip for better wheel support:
  2. 2.```bash
  3. 3.python -m pip install --upgrade pip
  4. 4.# Newer pip supports more wheel formats including manylinux_2_28
  5. 5.`

Prevention

  • Use uv pip install which has better wheel resolution
  • Pin packages that have wheels: psycopg2-binary instead of psycopg2
  • Use Docker images with build tools pre-installed: python:3.11-slim includes gcc
  • For CI/CD, cache build dependencies:
  • ```yaml
  • # GitHub Actions
  • name: Install system dependencies
  • run: sudo apt-get install -y build-essential python3-dev
  • `
  • Consider cibuildwheel for creating your own wheels for distribution