Skip to main content

How to Resolve "error: command 'gcc' failed with exit status 1" in Python pip

When installing a Python package with pip, you may encounter the error command 'gcc' failed with exit status 1. This error signals that pip is attempting to compile a "C extension"—a part of the library written in the C programming language for performance—but the necessary C compiler (gcc) and related development tools are not installed on your system.

Many popular Python libraries (especially in data science, cryptography, and imaging) use C extensions to speed up computationally intensive tasks. To install these packages from source, your system must have a C compiler and the Python development headers available. This guide provides the installation commands needed to resolve this error on all major operating systems.

Understanding the Error: The Need for a C Compiler​

The Python interpreter itself is written in C. To allow Python packages to interface directly with the C language for performance, developers can write "C extension modules." When you install a package that includes them, pip may need to compile this C code on your machine. The command 'gcc' failed... error means this compilation step failed because the system could not find the necessary tools, most notably:

  • A C Compiler: Like GCC (the GNU Compiler Collection) on Linux or Clang on macOS.
  • Python Development Headers: Files (like Python.h) that allow C code to interact with the Python interpreter's internal API.

The General Solution: Installing Build Tools and Python Headers​

The fix is to install the appropriate development toolchain for your operating system. This usually involves two key packages:

  1. A "build essentials" or "development tools" package that includes gcc, g++, make, and other critical utilities.
  2. A Python "development" package (python3-dev or python3-devel) that provides the C header files.

Once these are installed, pip will be able to compile the C extensions successfully.

Installation Commands by Operating System​

Find your operating system below and run the corresponding command(s) in your terminal.

Debian / Ubuntu​

On Debian-based systems like Ubuntu, the build-essential and python3-dev packages provide everything you need.

Solution:

sudo apt update
sudo apt install build-essential python3-dev

Fedora / RHEL / CentOS​

On Red Hat-based systems, the "Development Tools" group and python3-devel package serve the same purpose.

Solution:

sudo dnf groupinstall "Development Tools"
sudo dnf install python3-devel

Arch Linux / Manjaro​

On Arch-based systems, the base-devel package group includes the C compiler and other essential tools.

Solution:

sudo pacman -Syu base-devel

macOS​

On macOS, the necessary tools are provided by Apple's Xcode Command Line Tools.

Solution: run the following command in your terminal. It will prompt you to install the tools if they are not already present.

xcode-select --install
note

In some cases, you may also need a specific compiler version provided by Homebrew. If the error persists after installing the Xcode Command Line Tools, you can try installing GCC via Homebrew: brew install gcc.

Windows​

On Windows, Python uses the Microsoft Visual C++ (MSVC) compiler, not GCC. You must install the Build Tools for Visual Studio.

Solution:

  1. Go to the Visual Studio Downloads page.
  2. Scroll down to the "Tools for Visual Studio" section and download the "Build Tools for Visual Studio" installer.
  3. Run the installer. In the "Workloads" tab, check the box for "C++ build tools".
  4. Click "Install" to complete the installation.

After the installation is finished, restart your terminal and try the pip install command again.

Conclusion​

The error: command 'gcc' failed with exit status 1 is not a Python-specific error but rather a system configuration issue. It indicates that your environment is missing the necessary C compiler toolchain required to build a Python package's C extensions.

The solution is to install the appropriate development tools and Python headers for your operating system:

  • Debian/Ubuntu: build-essential and python3-dev
  • Fedora/RHEL: "Development Tools" group and python3-devel
  • Arch/Manjaro: base-devel
  • macOS: xcode-select --install
  • Windows: C++ Build Tools for Visual Studio

Once these dependencies are installed, pip will be able to compile and install the package without issue.

Table of Contents