How to fix Python error: legacy-install-failure

Posted on Jan 16, 2023


When running a pip install command, you might encounter a Python error that says error: legacy-install-failure.

For example, I got this error when installing locustio package:

$ pip3 install locustio
Collecting locustio
...
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.
╰─> locustio

This error happens because there’s an issue with the package you are trying to install.

To fix this error, you need to see the error output for hints.

Here are a few steps you can take to troubleshoot and fix this error:

Upgrade pip and other build tools

Before you run another install, try to upgrade your pip, wheel, and setuptools to the latest version first:

# upgrade pip
pip install --upgrade pip

# or if you have pip3
pip3 install --upgrade pip

# if you don't have pip in PATH
python -m pip install --upgrade pip
python3 -m pip install --upgrade pip

# for Windows
py -m pip install --upgrade pip

# upgrade setuptools and wheel

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

Once you upgraded these packages, try installing the package again.

If successful, you can skip the solutions below.

Check if the package has moved to a different name

This error can appear when the package you want to install has moved to a different name.

In case of the locustio package, the developers have moved the package name to locust as shown in the error message:

**** Locust package has moved from 'locustio' to 'locust'. 
Please update your reference (or pin your version to 0.14.6 
if you dont want to update to 1.0) ****
      
      [end of output]

This means you need to change the package name when running pip install:

pip install locust  # ✅
# or
pip3 install locust  # ✅

With that, you should be able to install the package without any issue.

For macOS: Ensure you have an active developer path

If you’re on Mac, you might require the Xcode Command Line Tools to fix this error.

You can tell if you need the tools when you have this error message:

xcrun: error: invalid active developer path ...
missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun

The above error means you need to install the Xcode Command Line Tools.

Run the following command:

xcode-select --install

And you should be able to install the package without issue.

For Windows: You need to have Microsoft C++ Build Tools

If you’re on Windows, you might require Microsoft Visual C++ compiler to fix this error.

The error message should tell you as shown below:

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/>

      [end of output]

You need to install the compiler version that’s compatible with your Python version:

Compiler 14.x for Python 3.5 - 3.10 Compiler 10.0 for Python 3.3 - 3.4 Compiler 9.0 for Python 2.6-2.7, 3.0 - 3.2

The compiler is included in Microsoft Visual Studio, so you can install Visual Studio and activate Python development workload as follows:

You can also activate Data Science workload as an extra.

If you already have Visual Studio installed, activate the workload from the menu Tools > Get Tools and Features.

Alternatively, you can also install stand-alone Microsoft C++ Build Tools.

Once you have the build tools installed, you should be able to install the package.

Extra: See if the package has a wheel distribution

If you still can’t install the package, you can try to download the wheel distribution and install it directly on your computer

For example, suppose you want to install the gensim package. You can look into the pypi.org files directory as shown below:

You need to download the right wheel distribution for your system. If you use Windows, download the file with win_ in its name.

macOS should use the macosx_ packages (x86_64 for Intel Mac, universal for Apple Silicone)

Finally, Linux users should use the manylinux_ packages (x86_64 for Intel devices, aarch64 for ARM devices)

After you download the file, install it using pip as follows:

pip install gensim-4.3.0-cp311-cp311-win_amd64.whl
# or
pip3 install gensim-4.3.0-cp311-cp311-win_amd64.whl

A wheel package can be installed without going through the build process, so you don’t need to install the build tools anymore.

Conclusion

The solution to the error: legacy-install-failure depends on what package you are trying to install with pip.

Some packages may have been moved to a different name, some may need the build tools for the Operating System to be available.

If all else fails, try to download the .whl package directly from pypi.org and install it yourself.

I hope this article helps you fix the legacy-install-failure error in Python. 🙏

Level up your programming skills

I'm sending out an occasional email with the latest programming tutorials. Drop your email in the box below and I'll send new stuff straight into your inbox!

No spam. Unsubscribe anytime.