How to Fix the subprocess-exited-with-error in Python

When installing Python packages using pip, you may encounter the frustrating “subprocess-exited-with-error” message. This error occurs when pip fails to execute the installation script of a package successfully.

error: subprocess-exited-with-error

In this post, I’ll explain the common causes of this error and how to fix it. Follow the solutions here to get your Python package installations back on track!

What Causes the Subprocess-Exited-With-Error in Python

There are a few main reasons why you could get the subprocess error when trying to pip install a package:

1. Missing Build Tools

Some Python packages require additional build tools like a C compiler to install properly. For example:

error: Microsoft Visual C++ 14.0 or greater is required. Get it with "Build Tools for Visual Studio"  

Here the package needs the Visual Studio build tools to compile.

2. Incompatible OS

The package may not officially support the OS you are currently using. Trying to pip install on an unsupported OS will result in errors.

For example, the tts package does not work on macOS with Apple Silicon:

error: subprocess-exited-with-error

× Running install for mecab-python3 did not run successfully.
│ exit code: 1

3. Unsupported Python Version

If you are running a brand new version of Python that a package doesn’t support yet, the installation may fail with subprocess errors:

RuntimeError: Cannot install on Python version 3.11; only versions >=3.7,<3.11 are supported.

4. Outdated Python or pip

Using older versions of Python or pip can also cause issues when trying to install packages that require newer versions.

How to Fix Missing Build Tools for Python Packages

If you see an error indicating a build tool like Visual Studio or gcc is missing, you first need to install the required tool.

For example, to fix the Visual Studio build tools error on Windows:

  1. Download and install Build Tools for Visual Studio.
  2. Open an administrative command prompt and run:
npm install --global --production windows-build-tools

This will install the necessary compilers and tools for compiling Python packages in Windows.

After installing the build tools, try running pip install again for the package.

You can also upgrade pip, setuptools, and wheel to latest versions in case that helps:

pip install --upgrade pip setuptools wheel

Ensure Python Version Compatibility

Check the package documentation on PyPI to see which Python versions it supports. If you are running an older unsupported Python version, update to a newer supported version.

You can also try creating a virtual environment with the required Python version using venv before installing the package.

Update Pip Dependencies

Make sure pip, setuptools, and wheel are up to date by running:

pip install --upgrade pip
pip install --upgrade setuptools wheel

This will upgrade any outdated pip dependencies that could be causing issues.

Installing Python Packages on an Unsupported OS

If a package does not officially support your operating system, you have a couple options:

  • Use a supported OS – Create a supported OS virtual machine and install the package there.
  • Install dependencies manually – On Apple Silicon for example, you may need to manually install the package dependencies using Homebrew before pip installing the package itself.

Checking the package documentation should indicate any specific OS requirements and workarounds.

Downgrade Python to Install Unsupported Packages

For packages that don’t support the latest Python version yet, downgrade Python to a supported version:

  1. Use pyenv to install an older Python version like 3.8 or 3.9.
  2. Create a virtual environment with this Python version:
python -m venv env
  1. Activate the virtual environment:
source env/bin/activate
  1. Install the package within the virtual environment.

This allows you to keep your system Python intact while installing and using the package in the virtual env.


The “subprocess-exited-with-error” during Python package installation can be frustrating but is usually fixable. By identifying the specific cause and following the appropriate solution, you can get back to coding in Python!

The key is to check for missing build tools, Python version incompatibilities, outdated pip/Python, and any other installation prerequisites specified for the package. Both pip and the package documentation are there to help guide you.

I hope this overview gives you a better understanding of the subprocess error and how to troubleshoot it in Python. Let me know if you have any other tips to share!

Scroll to Top