Skip to main content

How to Resolve "ERROR: Command errored out with exit status 1" in Python pip:

When installing a Python package with pip, the ERROR: Command errored out with exit status 1 is a generic failure message. It indicates that a subprocess, typically the package's setup.py script, has failed. The error message itself is just a summary of the failure; the real cause is always located in the lines of text above this final error message in your terminal's output.

Learning to read this output is the key to solving the problem. This guide will teach you how to interpret the pip logs and will walk you through the most common underlying issues and their solutions, such as missing compilers or system-level dependencies.

How to Read the Error Log​

The "exit status 1" message is the last thing pip prints. To find the actual problem, you must scroll up in your terminal and look for the first error: message or other key phrases that describe what went wrong during the build process.

The log will often contain hundreds of lines from the compilation process, but you are looking for the specific error that halted it. It is usually just above the long horizontal line of dashes (----).

Common Cause 1: Missing C/C++ Compiler and Build Tools​

Many high-performance Python packages (like NumPy, pandas, or cryptography libraries) are written partially in C or C++ for speed. To install them from a source distribution, pip needs to compile this C/C++ code, which requires a compiler.

Example of Error Log Clue (in Windows): when installing a package like NumPy on Windows without the necessary tools, you might see this:

... (many lines of build output) ...
error: Microsoft Visual C++ 14.0 or greater is required. Get it with "Microsoft C++ Build Tools": https://visualstudio.microsoft.com/visual-cpp-build-tools/
----------------------------------------
ERROR: Command errored out with exit status 1: ...

The log explicitly tells you what is missing: "Microsoft Visual C++ 14.0 or greater".

Solution: install the appropriate C/C++ build toolchain for your operating system.

  • Windows: Download and install "Build Tools for Visual Studio" from the Visual Studio Downloads page. Make sure to select the "C++ build tools" workload in the installer.
  • Debian/Ubuntu: sudo apt install build-essential python3-dev
  • Fedora/RHEL/CentOS: sudo dnf groupinstall "Development Tools" and sudo dnf install python3-devel
  • macOS: Install the Xcode Command Line Tools with xcode-select --install.

Common Cause 2: Missing Non-Python System Dependencies​

Many Python packages are "wrappers" around existing non-Python libraries. The pip install process may fail if it cannot find the required system-level library or its development headers.

Example of Error Log Clue (in psycopg2): when installing psycopg2 (a PostgreSQL adapter) without the necessary client libraries, the log is very informative:

... (many lines of build output) ...
Error: pg_config executable not found.

pg_config is required to build psycopg2 from source. Please add the directory
containing pg_config to the $PATH...

If you prefer to avoid building psycopg2 from source, please install the PyPI
'psycopg2-binary' package instead.
----------------------------------------
ERROR: Command errored out with exit status 1: ...

The log clearly states that pg_config executable not found and even suggests a solution: install the pre-compiled psycopg2-binary package instead.

Solution:

  1. Read the log to identify the missing dependency (e.g., pg_config, libxml2, openssl).
  2. Install the development package for that library using your system's package manager.
    • For psycopg2 on Debian/Ubuntu, the command is sudo apt-get install libpq-dev.
  3. Alternatively, install a pre-compiled binary version of the Python package if one is available (e.g., pip install psycopg2-binary). This is often the easiest solution as it avoids compilation entirely.

Common Cause 3: Outdated Packaging Tools (pip, setuptools, wheel)​

Sometimes, the package you are trying to install uses modern packaging features that your older version of pip, setuptools, or wheel does not understand. This can cause the setup.py script to fail.

Solution: this is often the quickest thing to try. Upgrading your packaging tools can resolve many obscure build errors.

python3 -m pip install --upgrade pip setuptools wheel

After running this command, try to install your target package again.

Conclusion​

The ERROR: Command errored out with exit status 1 is a generic message, but the solution is almost always found within the detailed log output that pip provides. Your troubleshooting process should be:

  1. Read the Logs: Scroll up from the final error message and find the specific error that caused the build to fail.
  2. Upgrade Packaging Tools: As a first step, run python3 -m pip install --upgrade pip setuptools wheel.
  3. Install Missing Dependencies:
    • If the log mentions a C/C++ compiler (like gcc or Microsoft Visual C++), install the build tools for your OS.
    • If the log mentions a specific library or executable (like pg_config or libxml2), install its development version using your system's package manager (e.g., apt, dnf, brew).
  4. Consider a Binary Package: If the log suggests it or one is available (e.g., psycopg2-binary), try installing that version to skip the compilation step entirely.

By learning to interpret the pip logs, you can turn this intimidating error into a clear set of actionable steps.

Table of Contents