Error: metadata-generation-failed. Encountered error while generating package metadata

# Table of Contents

# Error: metadata-generation-failed. Encountered error while generating package metadata

The error "metadata-generation-failed. Encountered error while generating package metadata" occurs for multiple reasons:

Having an outdated version of pip and setuptools.
Having a Python version that is not supported by the package you're trying to install.
Misspelling the name of the package.
Having missing dependencies.

error metadata generation failed encountered error

shell

Copied!
error: subprocess-exited-with-error

× python setup.py egg_info did not run successfully.
│ exit code: 1
╰─> [1 lines of output]
    ERROR: Can not execute `setup.py` since setuptools is not available in the build environment.
    [end of output]

error: metadata-generation-failed

× Encountered error while generating package metadata.
╰─> See above for output.

note: This is an issue with the package mentioned above, not pip.
hint: See above for details.

# Try installing the package with the `--use-deprecated` option

The first thing you should try is to run the pip install command with the --use-deprecated option.

shell

Copied!
pip install numpy --use-deprecated=legacy-resolver
pip3 install numpy --use-deprecated=legacy-resolver

python -m pip install numpy --use-deprecated=legacy-resolver
python3 -m pip install numpy --use-deprecated=legacy-resolver
py -m pip install numpy --use-deprecated=legacy-resolver

Make sure to replace numpy with the name of the package you're trying to install.

The --use-deprecated option allows us to use the old resolver behavior when installing modules.

If you have an older version of pip, you have to set the --use-deprecated option to backtrack-on-build-failures.

shell

Copied!
pip install numpy --use-deprecated=backtrack-on-build-failures
pip3 install numpy --use-deprecated=backtrack-on-build-failures

python -m pip install numpy --use-deprecated=backtrack-on-build-failures
python3 -m pip install numpy --use-deprecated=backtrack-on-build-failures

# Checking if your Python version is supported by the package

If the suggestions didn't help, read toward the end of your error message.

It might contain information such as: "RuntimeError: Cannot install on Python version 3.11.0; only versions >=3.7,<3.11 are supported."

In this case, you have to use a Python version that is supported by the package.

# Installing missing dependencies

Your error message might also contain a missing package you have to install, e.g. "ModuleNotFoundError: No module named 'auxlib'".

In this case, you have to install the auxlib package before installing the other package.

shell

Copied!
pip install auxlib
pip3 install auxlib

python -m pip install auxlib
python3 -m pip install auxlib

Make sure to replace auxlib with the package from your error message.

# Misspelling the name of the package (e.g. installing `dotenv`)

Another common cause of the error is misspelling the name of the package and trying to install some broken, obsolete module by mistake.

For example, the error is caused when you try to install the python-dotenv module as pip install dotenv.

shell

Copied!
# ⛔️ Error: The package is not named dotenv
pip install dotenv
pip3 install dotenv

Make sure to specify the correct installation command.

shell

Copied!
# ✅ Specifying the correct name of the package
pip install python-dotenv
pip3 install python-dotenv

You can google for "pypi {your_package_name}" and click on the first result to make sure the name of the package is correct.

copy installation command

You can also search for a package directory on the PyPI page.

# Update your version of `pip`

If none of the suggestions helped, try upgrading your pip version before installing the package.

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

Copied!
# 👇️ 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

# 👇️ If you don't have pip in your PATH environment variable
python3 -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

# Update `setuptools` and `wheel`

After you upgrade pip, upgrade setuptools as well.

shell

Copied!
pip install --upgrade setuptools
pip3 install --upgrade setuptools

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

Try to install the package now that your pip version is upgraded.

shell

Copied!
pip install numpy
pip3 install numpy

python -m pip install numpy
python3 -m pip install numpy
py -m pip install numpy

Make sure you aren't trying to install a module that is built into the standard Python library, e.g. the email module. You can directly import built-in modules without installing them.

If none of the suggestions helped, make sure your Python version is supported by the package.

# Install the module with the `--pre` option

The error often occurs when the package you are trying to install does not support your version of Python.

To solve the error, try running the pip install command with the --pre option.

shell

Copied!
pip install pygame --pre
pip3 install pygame --pre

python -m pip install pygame --pre
python3 -m pip install pygame --pre
py -m pip install pygame --pre

The pygame module often causes the error because the module hasn't been updated to support the latest versions of Python.

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

This might help because more recent versions of the package might have added support for the newer Python versions.

# Check if your Python version is supported by the package

Google for the name of the package and check if your Python version is supported by the package.

For example, if I google "requests pypi" and click on the pypi.org page, I can see the supported Python versions in the sidebar on the left, under Meta > Requires.

supported python versions by package

The screenshot shows that the package supports Python 3.7+.

If your Python version doesn't meet the requirements, the error occurs.

Your error message will likely contain something like "RuntimeError: Cannot install on Python version 3.11.0; only versions >=3.7,<3.11 are supported."

If you have multiple Python versions, you might have selected an incorrect interpreter in your IDE.

If you use VS Code, check out this article on how to change your Python version and select the correct interpreter.

If the package doesn't support the latest version of Python, try running the pip install command with the --pre option.

shell

Copied!
pip install requests --pre
pip3 install requests --pre

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

Make sure to replace requests with the name of the actual package you are trying to install.

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

If that doesn't work, you have to install a Python version that is in the specified range and then run the pip install <package_name> command.

You can upgrade your Python version by downloading the installer from the official python.org website and running it.

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)

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

# Try running pip install in verbose mode

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

shell

Copied!
pip install requests -vvv

pip3 install requests -vvv

python -m pip install requests -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 "metadata-generation-failed. Encountered error while generating package metadata", make sure:

Your pip and setuptools versions are up to date.
Your version of Python is supported by the package you're trying to install.
You haven't misspelled the name of the package.
You don't have any missing dependencies.

# Psycopg2 error: metadata-generation-failed in Python

Here is an example of solving the error for a specific package - psycopg2.

The error "metadata-generation-failed" when installing psycopg2 occurs for multiple reasons:

Not having the dependencies of psycopg2 installed.
Having an outdated version of pip, setuptools or wheel.
Having a Python version that isn't supported by psycopg2.

shell

Copied!
pip install psycopg2-binary

note: This error originates from a subprocess, and is likely not a problem with pip.
error: metadata-generation-failed

× Encountered error while generating package metadata.
╰─> See above for output.

If you are on Debian (Ubuntu), install the prerequisites before installing the psycopg2-binary package.

shell

Copied!
sudo apt-get install gcc libpq-dev python3-dev

If you are on macOS, make sure you have openssl installed.

shell

Copied!
# 👇️ Install `openssl`
brew install openssl

# 👇️ Add it to your LIBRARY_PATH env variable
export LIBRARY_PATH=$LIBRARY_PATH:/usr/local/opt/openssl/lib/

The openssl location might be different depending on your operating system, but is most commonly:

/usr/local/opt/openssl/lib/
/opt/homebrew/opt/openssl/lib

# Upgrade your versions of `pip`, `setuptools` and `wheel`

Update your versions of pip, setuptools and wheel.

shell

Copied!
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 psycopg2-binary command.

shell

Copied!
# 👇️ first, uninstall psycopg2 first
pip uninstall psycopg2

pip install psycopg2-binary
pip3 install psycopg2-binary

python -m pip install psycopg2-binary
python3 -m pip install psycopg2-binary

# 👇️ For Anaconda
conda install -c conda-forge psycopg2-binary

The psycopg2-binary module is a stand-alone package that doesn't require a compiler or external libraries.

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

shell

Copied!
pip install psycopg2-binary --pre
pip3 install psycopg2-binary --pre

python -m pip install psycopg2-binary --pre
python3 -m pip install psycopg2-binary --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

Copied!
pip install --no-use-pep517 psycopg2-binary
pip3 install --no-use-pep517 psycopg2-binary

python -m pip install --no-use-pep517 psycopg2-binary
python3 -m pip install --no-use-pep517 psycopg2-binary

# Check if your Python version is supported by the package

The error when installing psycopg2 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

Copied!
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)

# Try running pip install in verbose mode

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

shell

Copied!
pip install psycopg2-binary -vvv
pip3 install psycopg2-binary -vvv

python -m pip install psycopg2-binary -vvv
python3 -m pip install psycopg2-binary -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.

# 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.

You can use the search field on my Home Page to filter through all of my articles.

Error: metadata-generation-failed. Encountered error while generating package metadata

# Table of Contents