When running a pip install command, you might encounter a Python error that says:
error: legacy-install-failure
In my experience, this error occurs when the package you’re trying to install doesn’t support the latest Python version.
To resolve this error, you might need to upgrade Python build tools (pip, setuptools, and wheel) to the latest versions.
Usually, there are hints on the error output that shows precisely why this error occurs. This tutorial will show you how to fix the error in practice.
1. 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.
2. Check if the package was moved to a different name
This error can appear when the package you want to install was moved to a different name. You need to check the error output to see if this is true.
For instance, I tried to install the locustio package when I got this error:
```sh {hl_lines=[5]}
$ pip3 install locustio
Collecting locustio
...
**** 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) ****
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
The output above says that the package has moved from locustio to locust, so I changed the package name when running pip install like this:
pip install locust # ✅
# or
pip3 install locust # ✅
The installation went smoothly and I no longer receive the error. You might see the same output.
3. 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.
4. 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.
5. 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 Silicon)
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 error: legacy-install-failure occurs when the package you’re trying to install is not compatible with the Python version you installed.
You might not have the latest versions of Python build tools installed. Or the package may have been moved to a different name.
When all else fails, try to download the .whl package directly from pypi.org and install it yourself.
I hope this article helps. Thanks for reading! 🙏