Skip to main content

How to Resolve Python Pip Error "error: legacy-install-failure" (Running setup.py install did not run successfully)

When installing Python packages with pip, particularly those involving compiled C/C++ or Fortran extensions, you might encounter the error: legacy-install-failure. This is often accompanied by messages like Running setup.py install for package_name did not run successfully and exit code: 1. This error signals that pip could not find a pre-built binary "wheel" (.whl) file for your specific system (OS, Python version, architecture) and attempted to build the package from source using its setup.py script, but this build process failed.

This guide explains the common reasons for these build failures (missing compilers, development headers, incompatible versions) and provides comprehensive solutions.

Understanding the Error: Wheels vs. Source Builds (setup.py)​

pip prefers to install packages using pre-compiled binary distributions called wheels (.whl files). These wheels contain ready-to-use files for a specific operating system, Python version, and CPU architecture, avoiding the need for local compilation.

However, if pip cannot find a compatible wheel for your system on PyPI (Python Package Index), it falls back to downloading the package's source distribution (usually a .tar.gz or .zip file). This source code often includes extensions written in C, C++, or Fortran that need to be compiled locally. pip attempts this compilation by running the package's setup.py script (often using setuptools).

The legacy-install-failure error indicates that this local build process failed. The lines preceding the error usually contain more specific compiler errors indicating why the build failed.

Common Causes for Build Failures​

  • Missing C/C++ Compiler: Your system lacks a working C/C++ compiler (like GCC, Clang, or MSVC).
  • Missing Development Headers: Essential header files needed to compile against system libraries or the Python C API are missing (e.g., python3-dev on Debian/Ubuntu, python3-devel on Fedora/CentOS).
  • Missing Package-Specific Dependencies: The package requires other system libraries or tools to be installed before it can be built (e.g., database client libraries, scientific computing libraries like BLAS/LAPACK, OpenSSL headers).
  • Incompatible Python Version: The package source code might not be compatible with the version of Python you are using.
  • Outdated Build Tools: Older versions of pip, setuptools, or wheel might have bugs or lack support for modern build systems specified by the package.

Solution 1: Upgrade Build Tools (pip, setuptools, wheel) (Essential First Step)​

Always start by ensuring your core Python packaging tools are up-to-date. Newer versions often include improved build handling and compatibility.

# Use the command appropriate for your Python setup
python -m pip install --upgrade pip setuptools wheel
# Or: 
python3 -m pip install --upgrade pip setuptools wheel
# Or: 
py -m pip install --upgrade pip setuptools wheel (Windows)
note

Add --user if upgrading globally without admin rights and not in a venv. Avoid sudo unless absolutely necessary).

After upgrading, retry installing the original package. This simple step frequently resolves the issue.

Solution 2: Install System-Level Build Dependencies (Compilers & Headers)​

This is the most common fix when a source build fails. You need to install the necessary C/C++ compiler and development headers for your operating system.

Linux (Debian/Ubuntu, Fedora/CentOS/RHEL)​

  • Debian/Ubuntu/Mint: 
    sudo apt update
    sudo apt install build-essential python3-dev # python3-dev is crucial!
    (build-essential includes gcc, g++, make, etc.)
  • Fedora/CentOS/RHEL: 
    sudo yum update # or dnf update
    sudo yum groupinstall "Development Tools" -y
    sudo yum install python3-devel -y # Adjust python3-devel if needed (e.g., python3.9-devel)
    # Or using dnf:
    # sudo dnf groupinstall "Development Tools" -y
    # sudo dnf install python3-devel -y
    (Development Tools includes gcc, g++, make, etc.)

macOS (Xcode Command Line Tools)​

The easiest way is to install the Xcode Command Line Tools, which include Clang, Git, and other necessary build tools.

xcode-select --install

Follow the on-screen prompts. If already installed, you might need to update them via the App Store or softwareupdate --all --install --force.

Windows (Microsoft C++ Build Tools)​

Many Python packages with C extensions require the Microsoft Visual C++ (MSVC) compiler toolchain.

  1. Go to the Visual Studio Downloads page.
  2. Scroll down to "Tools for Visual Studio".
  3. Download the "Build Tools for Visual Studio" installer.
  4. Run the installer.
  5. Select the "C++ build tools" workload. Ensure the latest Windows SDK and core C++ tools are selected in the installation details on the right.
  6. Click "Install".

Package-Specific Dependencies (Examples)​

Read the error messages carefully! They often mention specific missing libraries or headers. You might need to install development versions of libraries like:

  • libssl-dev / openssl-devel (for packages needing OpenSSL, like older cryptography or grpcio)
  • Database client libraries (e.g., libpq-dev for PostgreSQL, default-libmysqlclient-dev for MySQL)
  • Scientific libraries (e.g., libblas-dev, liblapack-dev)

Example for grpcio on macOS (if standard install fails): Sometimes specific environment variables are needed during the pip install if compilers struggle to find dependencies:

# Ensure openssl installed via brew: brew install openssl
export GRPC_PYTHON_BUILD_SYSTEM_OPENSSL=true
export GRPC_PYTHON_BUILD_SYSTEM_ZLIB=true
# May need LDFLAGS/CPPFLAGS pointing to brew openssl/zlib install paths too
pip install grpcio
note

After installing system dependencies, always retry pip install <package-name>.

Solution 3: Check Python Version Compatibility​

Verify that the package version you're trying to install supports your Python version.

  • Check the package's page on PyPI (https://pypi.org/project/package-name/). Look under "Meta" -> "Requires" or check the "Download files" section for available wheels (.whl files). Wheel filenames often indicate compatibility (e.g., cp310 means CPython 3.10, py3 means Python 3 generally).
  • Check your Python version: python --version.
  • If your Python version isn't listed or doesn't have a wheel, you might need to:
    • Install an older version of the package that does support your Python (pip install package-name==X.Y.Z).
    • Upgrade (or downgrade) your Python installation to a version supported by the package.

Solution 4: Use Pre-Built Wheels (Especially for Windows)​

For some complex scientific packages on Windows, community members like Christoph Gohlke provide pre-compiled wheels when official ones aren't available on PyPI.

  1. Go to the Unofficial Windows Binaries for Python Extension Packages site.
  2. Find your package.
  3. Download the .whl file that matches your Python version (e.g., cp310 for Python 3.10) and architecture (win32 for 32-bit, amd64 for 64-bit Python). Check your Python architecture by running python in the terminal – it usually says 32-bit or 64-bit.
  4. Open your terminal/cmd/powershell in the directory where you downloaded the file.
  5. Install using pip: 
    pip install "package_name‑version‑cpXY‑cpXY‑win_arch.whl"
    # Example: pip install "numpy‑1.23.4+mkl‑cp310‑cp310‑win_amd64.whl"

Solution 5: Other Pip Flags (Workarounds/Diagnostics)​

  • --upgrade: Sometimes installing dependencies first and then running pip install --upgrade <package-name> can help resolve intermediate dependency issues.
  • --no-cache-dir: Disables the pip cache. Unlikely to fix a build error but can help if corrupted downloads are suspected.
  • --pre: Installs pre-release/development versions. A newer pre-release might have fixed the build issue or included a needed wheel. Use with caution.
  • --no-use-pep517: (Use with Caution) This forces pip to use the older setup.py install mechanism directly, bypassing the modern pyproject.toml build system interface (PEP 517/518). This might work for packages with broken modern build configurations but can hide other problems and isn't a proper long-term fix. Try only if other solutions fail.

Isolating project dependencies in a virtual environment (python -m venv venv, activate) prevents conflicts with globally installed packages and ensures you're installing into a clean space where you have permissions. While it doesn't install missing system build tools, it's essential for reliable dependency management.

Debugging: Using Verbose Output (-vvv)​

To get detailed logs about the build process and see the exact compiler errors, run pip with high verbosity:

pip install -vvv <package-name>

Scroll through the output to find error messages from the compiler (GCC, Clang, MSVC) which often indicate the specific missing header or library.

Conclusion​

The error: legacy-install-failure means pip failed to build a package from source, likely because it couldn't find a pre-built wheel for your system.

Key steps to resolve this:

  1. Upgrade Packaging Tools: python -m pip install --upgrade pip setuptools wheel.
  2. Install Build Dependencies: Install C/C++ compilers and Python development headers for your OS (e.g., build-essential + python3-dev on Ubuntu, Xcode tools on macOS, MSVC Build Tools on Windows). Check error logs for specific library dependencies.
  3. Check Python Version: Ensure the package version supports your Python version (check PyPI).
  4. (Windows) Look for unofficial pre-built wheels if official ones are missing.
  5. Use virtual environments for clean installations.
  6. Use verbose pip output (-vvv) to diagnose specific compiler errors.
  7. Consider pip flags like --pre or --no-use-pep517 only as secondary options or workarounds.

Addressing the missing build dependencies is the most common and effective solution for this error.

Table of Contents