Skip to main content

How to Resolve Python Pip Error error: command '...-gcc' failed with exit status 1"

When installing Python packages using pip, especially those containing C extensions, you might encounter a build failure indicated by the error: Setup script exited with error: command 'x86_64-linux-gnu-gcc' failed with exit status 1 (the specific compiler name might vary). This error means that pip attempted to compile C/C++ code required by the package, but the compiler (gcc or a similar one) encountered an error during the process and exited unsuccessfully.

This guide explains the common causes for these compilation failures – primarily missing Python development headers or other library dependencies – and provides solutions to install the necessary components.

Understanding the Error: Compilation Failure During Installation​

Many Python packages rely on underlying code written in C or C++ for performance or to interact with system libraries. When pip installs such a package and cannot find a pre-compiled binary "wheel" (.whl) file suitable for your system, it attempts to build the package from its source code. This involves invoking a C/C++ compiler (like gcc on Linux or clang on macOS) to compile the extension modules.

The error command '...-gcc' failed with exit status 1 signifies that the compiler command was executed, but it terminated with an error code (1), indicating the compilation step itself failed. This is different from errors where the compiler cannot be found (no acceptable C compiler).

Common Causes​

  • Missing Python Development Headers (Python.h): This is the most frequent cause. Compiling C extensions requires header files (.h) that describe Python's internal C API structure. These headers are usually not included in standard Python runtime installations and must be installed separately via a -dev or -devel package. The compiler error message often includes fatal error: Python.h: No such file or directory.
  • Missing C Compiler or Build Tools: While the error indicates the compiler ran, sometimes essential supporting tools (make, core libraries) might be missing or misconfigured, contributing to the failure.
  • Missing Package-Specific C Library Headers/Dependencies: The specific package being installed might depend on external C libraries (e.g., libssl, libxml2, libpq). The development headers for these libraries must also be installed for the compilation to succeed. The compiler error message usually points to the specific missing header file (e.g., fatal error: openssl/ssl.h: No such file or directory).

Solution 1: Install Python Development Headers (Primary Fix)​

Installing the development package corresponding to your Python version is usually the key solution.

note

You typically need administrator (sudo) privileges.

Debian/Ubuntu (python3-dev)​

sudo apt update

# Install headers for your default python3 version
sudo apt install python3-dev gcc build-essential

RHEL/CentOS/Fedora (python3-devel)​

sudo yum update # or dnf update

# Install headers for your default python3 version
sudo yum install python3-devel gcc -y

# May also need Development Tools group if minimal install:
# sudo yum groupinstall "Development Tools" -y
note

Use dnf instead of yum on newer Fedora/RHEL versions.

Alpine Linux (python3-dev)​

# Update package index first
apk update

# Install headers and build tools
apk add python3-dev gcc build-base libc-dev # build-base includes make, etc.

openSUSE (python3-devel)​

# Use the appropriate python3 version, e.g., python310-devel
sudo zypper install python3-devel gcc make

# May also need the base development pattern:
# sudo zypper install --type pattern devel_basis

macOS (Comes with Xcode Command Line Tools)​

Python headers are typically included with the Xcode Command Line Tools. Ensure they are installed:

xcode-select --install

If already installed, make sure they are up-to-date.

Windows (Included in Python Installer)​

The official Python installer from python.org for Windows usually includes the necessary headers. Ensure Python was installed correctly. If you encounter issues, consider repairing or reinstalling Python, ensuring development components are selected if prompted. Using the "C++ build tools" (see legacy-install-failure guide) is essential for compiling many packages on Windows.

Matching Python Version (python3.x-dev)​

If you have multiple Python versions installed (e.g., 3.9 and 3.10), you must install the development headers for the specific Python version you are using to run pip.

  1. Check your version: python --version or python3 --version
  2. Install the matching -dev/-devel package: 
    # Example for Python 3.10 on Debian/Ubuntu
    sudo apt install python3.10-dev build-essential gcc

    # Example for Python 3.9 on RHEL/CentOS/Fedora
    sudo yum install python3.9-devel gcc -y

After installing the correct headers, retry pip install <package-name>.

Solution 2: Ensure Build Tools Are Installed​

While Solution 1 often installs gcc and make as dependencies (via build-essential or Development Tools), explicitly ensuring they are present is good practice if Solution 1 alone doesn't work. Commands are usually included in the Solution 1 steps for each distribution.

Solution 3: Install Package-Specific Development Libraries​

If installing Python headers doesn't fix the error, carefully read the full error output from pip install. Look for lines just before the command '...-gcc' failed message. These lines usually contain the specific error from the gcc compiler.

  • Look for messages like fatal error: some_header.h: No such file or directory.
  • Identify the missing header (e.g., openssl/ssl.h, libxml/xpath.h, libpq-fe.h).
  • Search your distribution's package manager for the corresponding development package that provides this header file (often named lib<name>-dev or lib<name>-devel).

Common Examples:

# For openssl/ssl.h (e.g., cryptography, some network libs)
sudo apt install libssl-dev                     # Debian/Ubuntu
sudo yum install openssl-devel                  # RHEL/CentOS/Fedora

# For libxml/xpath.h (e.g., lxml)
sudo apt install libxml2-dev libxslt1-dev       # Debian/Ubuntu
sudo yum install libxml2-devel libxslt-devel    # RHEL/CentOS/Fedora

# For libpq-fe.h (e.g., psycopg2 source build)
sudo apt install libpq-dev                      # Debian/Ubuntu
sudo yum install postgresql-devel               # RHEL/CentOS/Fedora

Install the required development package(s) based on the compiler error message, then retry pip install.

Solution 4: Upgrade pip, setuptools, wheel​

Ensure your core packaging tools are up-to-date, as bugs in older versions can sometimes interfere with build processes.

python -m pip install --upgrade pip setuptools wheel

Debugging: Analyzing the Full Error Output​

The key to solving package-specific build failures (Solution 3) is reading the compiler's output. Use maximum verbosity with pip:

pip install -vvv <package-name>

Scroll up from the final error message and look for lines starting with gcc or containing error:. The specific error message there will guide you to the missing dependency.

Using Virtual Environments​

While virtual environments (venv or Conda) don't install system-level compilers or headers, using them is strongly recommended. It ensures you're installing packages into an isolated space and using the intended Python version, preventing conflicts with system packages or other projects. Always activate your virtual environment before running pip install.

Conclusion​

The error: command '...-gcc' failed with exit status 1 during pip install indicates a C/C++ compilation failure.

The most common solutions are:

  1. Install Python Development Headers: Find and install the -dev or -devel package matching your exact Python version (e.g., sudo apt install python3.10-dev).
  2. Install General Build Tools: Ensure gcc and build-essential (Debian/Ubuntu) or "Development Tools" (RHEL/CentOS/Fedora) are installed.
  3. Install Specific Library Headers: Examine the detailed compiler errors from the pip install -vvv output to identify and install any missing package-specific development libraries (e.g., libssl-dev, libpq-dev).
  4. Keep Packaging Tools Updated: python -m pip install --upgrade pip setuptools wheel.

By providing the necessary headers and tools for the compiler, you enable pip to successfully build packages from source when pre-compiled wheels aren't available.

Table of Contents