Skip to main content

How to Resolve Python Pip Error "subprocess-exited-with-error" During Package Installation

When installing Python packages using pip, you might encounter the frustrating error message: error: subprocess-exited-with-error. This often indicates that pip attempted to build a package from source (usually because a pre-compiled "wheel" file wasn't available for your system or Python version) and this build process failed. The error message itself points out: "This error originates from a subprocess, and is likely not a problem with pip."

This guide walks you through the common causes and provides a series of troubleshooting steps to resolve this package installation issue.

Understanding the "subprocess-exited-with-error"​

This error means pip launched another program (a subprocess) to perform a task – typically compiling code as part of building a package from its source code. That subprocess then exited with an error code, indicating it failed. The full error message often includes:

note: This error originates from a subprocess, and is likely not a problem with pip.
ERROR: Failed building wheel for <package-name>
ERROR: Could not build wheels for <package-name>, which is required to install pyproject.toml-based projects

The key is that pip itself is usually fine; the problem lies in the environment or dependencies needed by the package being installed.

Initial Troubleshooting Steps​

Upgrade pip, setuptools, and wheel​

Outdated packaging tools can sometimes cause issues. Start by upgrading them:

# For pip associated with your default 'python'
python -m pip install --upgrade pip setuptools wheel

# If using 'python3'
python3 -m pip install --upgrade pip setuptools wheel

# If 'py' launcher is used (Windows)
py -m pip install --upgrade pip setuptools wheel

# Or directly if pip is in your PATH
pip install --upgrade pip setuptools wheel
pip3 install --upgrade pip setuptools wheel

After upgrading, try installing your target package again.

Check for Missing System Dependencies (Compiler, Libraries)​

Many Python packages, especially those with C/C++ extensions (common in scientific computing, machine learning, etc.), require a compiler and development libraries to be present on your system to build from source. The error output (scroll up from the subprocess-exited-with-error message) often provides clues. Look for messages like:

  • error: Microsoft Visual C++ 14.0 or greater is required... (Windows)
  • unable to find vcvarsall.bat (Windows)
  • gcc: command not found (Linux/macOS)
  • fatal error: Python.h: No such file or directory (Linux/macOS - often means python development headers are missing)
  • ModuleNotFoundError: No module named 'some_build_dependency'

Addressing Build Failures​

Installing C++ Build Tools (Windows)​

If the error indicates a need for Microsoft Visual C++ build tools:

  1. Go to the Visual Studio Downloads page.
  2. Scroll down to "Tools for Visual Studio" and download "Build Tools for Visual Studio".
  3. Run the installer.
  4. In the "Workloads" tab, select "Desktop development with C++".
  5. Click "Install". After installation, you might need to restart your terminal or PC.

Installing Development Tools (Linux/macOS)​

  • Linux (Debian/Ubuntu): 
    sudo apt update
    sudo apt install build-essential python3-dev    # For Python 3
    # You might also need specific library headers, e.g., libffi-dev, libssl-dev
  • Linux (Fedora/CentOS/RHEL): 
    sudo dnf groupinstall "Development Tools"       # Or yum for older versions
    sudo dnf install python3-devel                  # For Python 3
  • macOS: Install Xcode Command Line Tools: 
    xcode-select --install

Python Version Compatibility​

Check Your Python Version​

python --version
# or
python3 --version

Check Package's Supported Python Versions (PyPI)​

  1. Go to PyPI (pypi.org) and search for the package you're trying to install.
  2. On the package's page, look for "Programming Language" classifiers or "Requires-Python" metadata (often in the sidebar or project description).
  3. Check the "Download files" section. Pre-compiled wheel files (.whl) often indicate Python version compatibility in their names (e.g., cp39 means CPython 3.9, cp310 means CPython 3.10). If there's no wheel for your Python version and OS, pip will try to build from source.

Consider Using a Supported Python Version​

If your Python version is too new or too old for the package, you might need to:

  • Install a different Python version that is supported.
  • Wait for the package maintainers to add support for your Python version.

pip Resolver and Pre-releases​

Using the Legacy Resolver (Older pip versions)​

For older pip versions, or if dependency resolution issues are suspected, you might try the legacy resolver (though this is generally not the first go-to):

pip install <package-name> --use-deprecated=legacy-resolver
# Or for even older pip:
pip install <package-name> --use-deprecated=backtrack-on-build-failures

Replace <package-name> with the actual package.

Installing Pre-release Versions (--pre)​

Sometimes, the latest stable release of a package might have issues, but a pre-release version (alpha, beta, release candidate) might have a fix or wheels for newer Python versions.

pip install <package-name> --pre

Using virtual environments is a best practice in Python development. It isolates project dependencies and can help avoid conflicts. If you're not already using one, create and activate one before installing packages:

# Create a virtual environment (use your python/python3 command)
python3 -m venv myenv

# Activate it:
source myenv/bin/activate   # Linux/macOS
myenv\Scripts\activate.bat  # Windows (cmd.exe):
myenv\Scripts\Activate.ps1  # Windows (PowerShell)

# Once activated, your prompt will change. Then upgrade pip and install:
pip install --upgrade pip
pip install <package-name>

Advanced Debugging​

Running pip install in Verbose Mode (-vvv)​

To get much more detailed output from pip, which can help pinpoint the exact step where the subprocess fails:

pip install <package-name> -vvv

The -v option can be used up to three times for increasing verbosity.

Inspecting the Full Error Output​

Carefully read the entire error message, not just the last few lines. Scroll up in your terminal output. The actual cause of the subprocess failure (e.g., a missing compiler, a C code error, a missing library) is usually printed much earlier in the output before pip reports the subprocess-exited-with-error.

Alternative: Downgrading pip (Last Resort)​

In rare cases, a very new version of pip might have an issue with a specific package. If all else fails, and you suspect a recent pip upgrade caused the problem, you could try downgrading pip to an older, known-stable version (e.g., 21.3.1 was often cited, but this is becoming less relevant):

pip install pip==21.3.1

This should be a last resort, as staying on an older pip isn't ideal long-term.

Conclusion​

The "subprocess-exited-with-error" from pip is a generic indicator that a package build failed. The key to solving it is to examine the full error output for specific messages from the failing subprocess. Common solutions include:

  • Upgrading pip, setuptools, and wheel.
  • Installing necessary system dependencies like C++ compilers and development headers.
  • Ensuring Python version compatibility.
  • Using virtual environments. Verbose output (pip install -vvv) is your best friend for diagnosing these issues.

Table of Contents