Fix error: metadata-generation-failed in Python

When running the pip install command to install a package, you might see the following error:

  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.

This error occurs because the setup.py file that your package has can’t be executed properly.

You should be able to see this error a few lines after you run the install command. For example, here I’m trying to install the dotenv package:

$ pip install dotenv
Collecting dotenv
  Using cached dotenv-0.0.5.tar.gz (2.4 kB)
  Preparing metadata (setup.py) ... error

When pip says Preparing metadata from setup.py, the result is an error.

But why does pip fail to generate metadata? It could be any one of the following causes:

1. You have outdated pip, setuptools, and wheel packages
2. The package is no longer maintained
3. The package doesn’t support the latest Python version yet
4. The package has external dependencies that must be met

This article shows examples of how this error occurs and how to fix it.

1. You have outdated build tools packages

Running the pip install command triggers the Python build systems which use the setuptools and wheels packages in the process.

This error can appear when you have outdated build tools in your system.

Before you try anything else, please upgrade these build tools to the latest versions.

You can use one of the following commands:

# For Unix/ macOS:
python3 -m pip install --upgrade pip setuptools wheel

# For windows:
py -m pip install --upgrade pip setuptools wheel

Once you upgraded the build tools to the latest versions, try installing the package again and see if it works now.

2. The package is no longer maintained

The other cause for this error is that the package you try to install is no longer maintained, so it causes an error when changes are introduced in setuptools or wheel package.

For example, the dotenv package hasn’t been updated in a while, so trying to install it with the latest Python version will cause an error.

Fortunately, there’s an alternative package for dotenv called python-dotenv that’s actively maintained.

If this is the cause for your package, then the only solution is to find an alternative that works.

3. The package doesn’t support the latest Python version yet

Sometimes, the package you try to install doesn’t support the latest version of Python.

This can happen when Python released a new stable version just a few days or weeks before, and you’re already upgrading it to the latest version.

For example, the pygame package uses C code, so it needs to rebuild a new wheel package for every Python version.

When there’s no wheel package for your Python version, pip will try to build the package from source. Most likely, it will fail because you don’t have the development environment to build the package successfully.

In the case of pygame, the maintainer has released a new wheels package as a developer build to test it for errors first.

You can install the latest developer build by adding the --pre option to the installation command as follows:

pip install pygame --pre

# If you have pip3:
pip3 install pygame --pre

Keep in mind that not all packages support the latest Python version even in their developer builds.

You need to ask the maintainers directly if this is the case with the package you want to install.

4. Your package has external dependencies that must be met

Some Python packages need to have their external dependencies met for the installation to run smoothly.

For example, database adapters like psycopg2 require the C compiler and other external dependencies. You need to have pg_config executable available in your system as well.

You can see the build prerequisites doc for more information.

UPDATE: There’s a new package called psycopg that uses pure Python code, so you might want to use that instead of psycopg2.

If you encounter this error, then you need to check on the homepage of your package and see if there are any requirements for installing that package.

Conclusion

As you can see, the Python error: metadata-generation-failed message has many possible causes.

The examples shown here are just a few causes for the error. You might even have a different cause altogether.

If you’re not sure how to fix the error, then you can try posting the error message on StackOverflow to get help.

If the package has a GitHub page, you can also check the issues page and see if there’s any mention of the same error.

I hope this tutorial is helpful. See you in other articles! 👋