Error: legacy-install-failure with pip install [Fixed]

avatar
Borislav Hadzhiev

Last updated: Apr 10, 2024
10 min

banner

# Error: legacy-install-failure with pip install [Fixed]

To solve the "Error: legacy-install-failure":

  1. Upgrade your versions of pip, setuptools and wheel before running pip install.
  2. Check if your Python version is supported by the package.
  3. On Windows, download and install the package from unofficial binaries.
  4. Try to install the package with the --pre option.
shell
Failed to build X
Installing collected packages: X
  × Running setup.py install for X did not run successfully.
  │ exit code: 1

note: This error originates from a subprocess, and is likely not a problem with pip.
error: legacy-install-failure

× Encountered error while trying to install package.
╰─> X

# Upgrade your versions of pip, setuptools and wheel

First, try to upgrade your pip, setuptools and wheel versions before running the pip install command.

Here are the commands for upgrading pip on all operating systems.

Which command works depends on your operating system and your version of Python.

shell
# 👇️ If you have pip already installed
pip install --upgrade pip

# 👇️ If your pip is aliased as pip3 (Python 3)
pip3 install --upgrade pip

# 👇️ If you don't have pip in your PATH environment variable
python -m pip install --upgrade pip
python3 -m pip install --upgrade pip
py -m pip install --upgrade pip

# 👇️ If you have easy_install
easy_install --upgrade pip

# 👇️ If you get a permissions error
sudo easy_install --upgrade pip

# 👇️ If you get a permissions error when upgrading `pip`
pip install --upgrade pip --user

# 👇️ Upgrade pip scoped to the current user (if you get a permissions error)
python -m pip install --user --upgrade pip
python3 -m pip install --user --upgrade pip

# 👇️ Installing directly from get-pip.py (MacOS and Linux)
curl https://bootstrap.pypa.io/get-pip.py | python

# 👇️ If you get permissions issues
curl https://bootstrap.pypa.io/get-pip.py | sudo python

# 👇️ Alternative for Ubuntu/Debian
sudo apt-get update && apt-get upgrade python-pip

# 👇️ Alternative for Red Hat / CentOS / Fedora
sudo yum install epel-release
sudo yum install python-pip
sudo yum update python-pip

upgrade pip version

Now that pip is upgraded, try to run the pip install <package> command.

shell
pip install requests
pip3 install requests

python -m pip install requests
python3 -m pip install requests
Make sure to replace requests with the name of the package you're trying to install.

If the error is not resolved, upgrade the setuptools and wheel packages as well.

shell
pip install --upgrade setuptools wheel
pip3 install --upgrade setuptools wheel

python -m pip install --upgrade setuptools wheel
python3 -m pip install --upgrade setuptools wheel
py -m pip install --upgrade setuptools wheel

upgrade setuptools and wheel

Try to rerun the pip install command after upgrading setuptools and wheel.

If you weren't able to upgrade pip or setuptools, follow the instructions in these articles:

# Run the pip install command with the --upgrade option

If that didn't help, try to run the pip install command with the --upgrade option.

shell
pip install requests --upgrade
pip3 install requests --upgrade

python -m pip install requests --upgrade
python3 -m pip install requests --upgrade

If the error is not resolved, try installing the package with the --no-cache-dir option to disable the cache.

shell
pip install requests --no-cache-dir
pip3 install requests --no-cache-dir

If that didn't help, use the --pre option to include pre-release and development versions of the package.

shell
pip install requests --pre
pip3 install requests --pre

python -m pip install requests --pre
python3 -m pip install requests --pre

The --pre option makes it so pip includes pre-release and development versions of the package. By default pip only finds stable versions.

This sometimes helps because a pre-release version of the package might have a wheel available for your version of Python.

If the error is not resolved, try running the pip install command with the --no-use-pep517 option.

shell
pip install --no-use-pep517 requests
pip3 install --no-use-pep517 requests

python -m pip install --no-use-pep517 requests
python3 -m pip install --no-use-pep517 requests

If you are on Windows, download a suitable .whl file for the package and install it.

If you aren't on Windows, scroll past the next subheading.

# Download and install a .whl file if you are on Windows

If you are on Windows, you can also download a suitable .whl file from the https://www.lfd.uci.edu/~gohlke/pythonlibs/ website.

First, get your Python version and check if your Python installation is 64-bit or 32-bit.

You can do that by opening CMD and typing python.

get python version and bits

For example, the screenshot shows that my Python version is 3.10 and my Python interpreter is 64-bit.

Now, click on the https://www.lfd.uci.edu/~gohlke/pythonlibs/ link, press CTRL + f and search for the name of the package.

Download the corresponding .whl file. For example, if I were trying to install the gensim package, I would download the following file.

shell
gensim‑4.2.0‑cp310‑cp310‑win_amd64.whl
The cp310 part is the version (Python 3.10) and amd64 means 64-bit.

Once you open the file, open your shell in the directory where the file is located (e.g. C:\Users\Example\Downloads) and install it using pip:

  1. Open the directory that contains the file in Explorer.
  2. Press Shift and right-click in Explorer.

windows open powershell window here

  1. Click on "Open PowerShell window here".
  2. Run the following command.
shell
pip install gensim‑4.2.0‑cp310‑cp310‑win_amd64.whl
pip3 install gensim‑4.2.0‑cp310‑cp310‑win_amd64.whl

Make sure to specify the name of the .whl file correctly as your Python version and the name of the package will likely be different.

# Installing Visual C++ build tools on Windows

If that didn't help and your error message contains something like: "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/", download Microsoft Build tools and check the "Desktop development with C++ checkbox when installing.

install microsoft build tools

# Check if your Python version is supported by the package

The error is sometimes caused when the package you are trying to install doesn't have available wheels for your version of Python.

You can check your Python version with the python --version command.

shell
python --version

get python version

You can check if a package has wheels available for a specific Python version in the Download files section of the package's pypi page.

For example, cp310 in the name of a file under "Built Distributions" means Python version 3.10 is supported for the specific operating system.

If you use multiple Python versions, make sure the correct Python interpreter is selected in your IDE.

If the .whl files are not available for your version of Python, you can download an older version.

You can download a specific Python version that is supported by the package if the package doesn't support the latest Python version.

Different versions are available in the "Looking for a specific release" table.

install specific python version

Make sure to tick the following options if you get prompted:

  • Install launcher for all users (recommended)
  • Add Python to PATH (this adds Python to your PATH environment variable)

# Check if the package has been renamed

The error is also caused when a package has been renamed.

For example, the Locust package has moved from 'locustio' to 'locust', so you would have to install locust instead of locustio.

shell
pip install locust
pip3 install locust

You can google "pypi package-name" to check if the package you're trying to install has been renamed.

# Installing Xcode developer tools on macOS

If your error message looks similar to the following:

shell
xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun

You have to install Xcode developer tools before installing the package.

shell
xcode-select --install

Rerun your pip install command after installing the Xcode command line tools.

# Create a virtual environment

If the error persists, try creating a virtual environment.

  1. Create a virtual environment.
  2. Activate the virtual environment.
  3. Run the pip install command with the virtual environment active.
shell
# 👇️ Use the correct version of Python when creating VENV
python3 -m venv venv

# 👇️ Activate on Unix or MacOS
source venv/bin/activate

# 👇️ Activate on Windows (cmd.exe)
venv\Scripts\activate.bat

# 👇️ Activate on Windows (PowerShell)
venv\Scripts\Activate.ps1

# 👇️ Install the specific package in the virtual environment
pip install gensim

If the python3 -m venv venv command doesn't work, try the following 2 commands:

  • python -m venv venv
  • py -m venv venv

Make sure to use the correct command to activate your virtual environment depending on your operating system and your shell.

Your virtual environment will use the version of Python that was used to create it.

# Try running pip install in verbose mode

If none of the suggestions helped, try running the pip install command in verbose mode.

shell
pip install numpy -vvv

pip3 install numpy -vvv

python -m pip install numpy -vvv

The -v option stands for verbose mode and can be used up to 3 times.

When the pip install command is run in verbose mode, the command shows more output and how the error occurred.

# Conclusion

To solve the "Error: legacy-install-failure":

  1. Upgrade your versions of pip, setuptools and wheel before running pip install.
  2. Check if your Python version is supported by the package.
  3. On Windows, download and install the package from unofficial binaries.
  4. Try to install the package with the --pre option.

# Examples of solving the error for specific packages

Here are 2 examples of solving the error when installing specific packages.

# Table of Contents

  1. wxPython error: legacy-install-failure
  2. grpcio error: legacy-install-failure

# wxPython error: legacy-install-failure

To solve the error when installing wxPython, run the pip install --upgrade pip setuptools wheel command to upgrade your pip, setuptools and wheel versions and rerun the pip install wxPython command.

shell
× Running setup.py install for wxPython did not run successfully.
  │ exit code: 1
note: This error originates from a subprocess, and is likely not a problem with pip.
error: legacy-install-failure

× Encountered error while trying to install package.
╰─> wxPython

Run the following commands to upgrade pip, setuptools and wheel.

shell
pip install --upgrade pip
pip3 install --upgrade pip

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

Now that pip is upgraded, try to run the pip install wxPython command.

shell
pip install wxPython
pip3 install wxPython

python -m pip install wxPython
python3 -m pip install wxPython
py -m pip install wxPython

conda install -c conda-forge wxpython

If that didn't help, use the --pre option to include pre-release and development versions of the package.

shell
pip install wxPython --pre
pip3 install wxPython --pre

python -m pip install wxPython --pre
python3 -m pip install wxPython --pre

The --pre option makes it so pip includes pre-release and development versions of the package. By default pip only finds stable versions.

This sometimes helps because a pre-release version of the package might have a wheel available for your version of Python.

# Check if your Python version is supported by the package

The error when installing wxPython is sometimes caused when the package you are trying to install doesn't have available wheels for your version of Python.

You can check your Python version with the python --version command.

shell
python --version

get python version

You can check if a package has wheels available for a specific Python version in the Download files section of the package's pypi page.

For example, cp310 in the name of a file under "Built Distributions" means Python version 3.10 is supported for the specific operating system.

If the .whl files are not available for your version of Python, you can download an older version.

You can download a specific Python version that is supported by the package if the package doesn't support the latest Python version.

Different versions are available in the "Looking for a specific release" table.

install specific python version

Make sure to tick the following options if you get prompted:

  • Install launcher for all users (recommended)
  • Add Python to PATH (this adds Python to your PATH environment variable)

# grpcio error: legacy-install-failure with pip install

To solve the "error: legacy-install-failure" when installing grpcio, run the pip install --upgrade pip setuptools wheel command to upgrade your pip, setuptools and wheel versions and rerun the pip install grpcio command.

shell
Failed to build grpcio
Installing collected packages: grpcio
  × Running setup.py install for grpcio did not run successfully.
  │ exit code: 1

note: This error originates from a subprocess, and is likely not a problem with pip.
error: legacy-install-failure

× Encountered error while trying to install package.
╰─> grpcio

If you are on macOS, try setting the GRPC_PYTHON_BUILD_SYSTEM_OPENSSL and GRPC_PYTHON_BUILD_SYSTEM_ZLIB variables to true before installing grpcio.

shell
GRPC_PYTHON_BUILD_SYSTEM_OPENSSL=true GRPC_PYTHON_BUILD_SYSTEM_ZLIB=true pip install grpcio

# 👇️ If you use Anaconda
conda install -c conda-forge grpcio

Run the following commands to upgrade pip, setuptools and wheel.

shell
pip install --upgrade pip
pip3 install --upgrade pip

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

Now that pip is upgraded, try to run the pip install grpcio command.

shell
pip install grpcio
pip3 install grpcio


python -m pip install grpcio
python3 -m pip install grpcio
py -m pip install grpcio

conda install -c conda-forge grpcio

If that didn't help, use the --pre option to include pre-release and development versions of the package.

shell
pip install grpcio --pre
pip3 install grpcio --pre

python -m pip install grpcio --pre
python3 -m pip install grpcio --pre

The --pre option makes it so pip includes pre-release and development versions of the package. By default pip only finds stable versions.

This sometimes helps because a pre-release version of the package might have a wheel available for your version of Python.

# Check if your Python version is supported by the package

The error when installing grpcio is sometimes caused when the package you are trying to install doesn't have available wheels for your version of Python.

You can check your Python version with the python --version command.

shell
python --version

get python version

You can check if a package has wheels available for a specific Python version in the Download files section of the package's pypi page.

For example, cp310 in the name of a file under "Built Distributions" means Python version 3.10 is supported for the specific operating system.

If the .whl files are not available for your version of Python, you can download an older version.

You can download a specific Python version that is supported by the package if the package doesn't support the latest Python version.

Different versions are available in the "Looking for a specific release" table.

install specific python version

Make sure to tick the following options if you get prompted:

  • Install launcher for all users (recommended)
  • Add Python to PATH (this adds Python to your PATH environment variable)

# Additional Resources

You can learn more about the related topics by checking out the following tutorials:

I wrote a book in which I share everything I know about how to become a better, more efficient programmer.
book cover
You can use the search field on my Home Page to filter through all of my articles.
About
Contacts
Policy
Terms & Conditions
GitHubLinkedin

Copyright © 2025 Borislav Hadzhiev

0
.........
.........
.........
.........
.........
.........
.........
.........
.........
.........
.........
.........
.........
.........
.........
.........
.........
.........