How to fix How to fix 'ERROR: Metadata generation failed' in Python in Python

PythonINTERMEDIATEMEDIUMUpdated Dec 7, 2025· 287 views

This error indicates pip could not generate package metadata. This typically happens when a package's setup.py or setup.cfg is invalid or runs code that fails.

Quick fix

Fixes How to fix 'ERROR: Metadata generation failed' in Python

  1. Verify the root cause
  2. Apply the appropriate fix
  3. Retry the installation
python — error
# How to fix 'ERROR: Metadata generation failed' in Python

What this error means

When pip installs a package, it first reads the package's metadata (version, dependencies, etc.). This metadata comes from setup.py, setup.cfg, or pyproject.toml. If pip cannot read or generate this metadata—often because setup.py raises an error or is malformed—installation fails with a metadata generation error.

Typical symptoms

  • pip install fails with 'ERROR: Metadata generation failed'
  • Error message includes 'ERROR: METADATA generation failed'
  • Works with older pip but fails with newer version
  • Specific package fails to install
  • setup.py has syntax errors or problematic imports
  • Metadata errors appear before wheel building
  • Works in one environment but not another

Common causes

  1. setup.py contains syntax errors or invalid code
  2. setup.py imports modules that are not installed
  3. Malformed setup.cfg or pyproject.toml
  4. Incompatible setuptools version
  5. setup.py tries to read files that don't exist
  6. Python version incompatible with setup.py code
  7. setup.py uses deprecated distutils API

How to fix this error

1Verify the root cause

Review the error message above and identify which cause applies to your situation. Run additional diagnostics if needed.

2Apply the appropriate fix

Follow the corresponding solution from the causes section above.

3Retry the installation

Once you've addressed the root cause, try running 'pip install' again.

Frequently asked questions

What does "How to fix 'ERROR: Metadata generation failed' in Python" mean?
). toml. py raises an error or is malformed—installation fails with a metadata generation error.
How do I fix "How to fix 'ERROR: Metadata generation failed' in Python"?
This error indicates pip could not generate package metadata. This typically happens when a package's setup.py or setup.cfg is invalid or runs code that fails.
What causes "How to fix 'ERROR: Metadata generation failed' in Python"?
setup.py contains syntax errors or invalid code setup.py imports modules that are not installed Malformed setup.cfg or pyproject.toml
Is the "How to fix 'ERROR: Metadata generation failed' in Python" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading