importlib-metadata

9.0.0 verified Tue May 12 auth: no python install: verified quickstart: verified

importlib-metadata provides third-party access to the functionality of the stdlib importlib.metadata module, including features backported from future Python versions. It allows reading installed package metadata such as version strings, entry points, file lists, and requirements. Current version is 9.0.0 (requires Python >=3.10). New features are introduced here first and later merged into CPython; releases track CPython closely with frequent minor/patch releases.

pip install importlib-metadata

Common errors

error ModuleNotFoundError: No module named 'importlib_metadata' ↓

cause This error occurs when the 'importlib-metadata' backport package is not installed in the Python environment, which is necessary for Python versions prior to 3.8 or if a dependency explicitly requires the backport.

fix

Install the 'importlib-metadata' package using pip: pip install importlib-metadata

error ModuleNotFoundError: No module named 'importlib.metadata' ↓

cause This typically happens when attempting to import the standard library module `importlib.metadata` on a Python version older than 3.8, where it was not yet included in the standard library.

fix

For Python versions 3.7 and older, install and import the backport: pip install importlib-metadata and then import importlib_metadata as metadata (or similar). For Python 3.8+, ensure your Python installation is complete and not corrupted.

error AttributeError: module 'importlib_metadata' has no attribute 'EntryPoints' ↓

cause This error arises when a consumer of `importlib-metadata` (e.g., a newer version of `setuptools`) expects a feature like the `EntryPoints` class (or an enhanced `entry_points` function signature) that was introduced in later versions of `importlib-metadata` (or Python's `importlib.metadata` in 3.10+), but an older version of the backport is installed.

fix

Upgrade the importlib-metadata package to its latest version: pip install --upgrade importlib-metadata.

error TypeError: entry_points() got an unexpected keyword argument 'group' ↓

cause This indicates that the `entry_points()` function being called does not support the `group` (or `name`) keyword arguments for filtering, a feature introduced in `importlib-metadata` 3.6 and Python 3.10's standard library `importlib.metadata`.

fix

Upgrade the importlib-metadata package to version 3.6 or newer: pip install --upgrade importlib-metadata, or ensure you are running Python 3.10 or newer if relying on the standard library module.

Warnings

breaking entry_points() no longer returns a dict. Since v5.0 it always returns an EntryPoints object. Code like entry_points()['console_scripts'] raises a TypeError. ↓

fix Use entry_points(group='console_scripts') to filter by group, or iterate the returned EntryPoints object directly.

breaking EntryPoint objects lost their tuple-like interface (__getitem__). Code that unpacked EntryPoints as tuples (e.g. name, ep = entry_point) fails silently or raises TypeError. ↓

fix Access entry point attributes by name: ep.name, ep.value, ep.group. Call ep.load() to import the target.

breaking metadata(pkg)['Missing-Key'] now raises KeyError instead of returning None. Previously absent keys silently returned None. ↓

fix Use metadata(pkg).get('Missing-Key') or wrap access in a try/except KeyError.

breaking Distribution subclasses that do not implement all abstract methods now raise errors. Deprecated compatibility shim was removed. ↓

fix Implement all abstract methods (read_text, locate_file) when subclassing Distribution for custom finders.

gotcha version() and metadata() operate on distribution package names (e.g. 'Pillow'), NOT import names (e.g. 'PIL'). They are frequently different and do not map 1-to-1. ↓

fix Use packages_distributions() to map an import name to its distribution name before calling version() or metadata().

gotcha importlib_metadata does not support stdlib modules or packages installed without dist-info/egg-info metadata. Calling version('os') raises PackageNotFoundError. ↓

fix Always catch PackageNotFoundError. For editable/local installs ensure the package was installed with pip install -e . so metadata is written.

deprecated On Python >=3.12 the stdlib importlib.metadata already incorporates features up to approximately importlib_metadata 5.x. For on-the-bleeding-edge features only, install the backport; otherwise prefer the stdlib to reduce dependencies. ↓

fix Check the stdlib/backport version correspondence table on PyPI before adding importlib-metadata as a hard dependency in projects targeting Python >=3.12.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.04s 18.1M

3.10 slim (glibc) - - 0.03s 19M

3.11 alpine (musl) - - 0.09s 20.0M

3.11 slim (glibc) - - 0.07s 20M

3.12 alpine (musl) - - 0.09s 11.8M

3.12 slim (glibc) - - 0.10s 12M

3.13 alpine (musl) - - 0.08s 11.5M

3.13 slim (glibc) - - 0.07s 12M

3.9 alpine (musl) - - 0.04s 17.6M

3.9 slim (glibc) - - 0.04s 18M

Imports

version
wrong
```
from importlib.metadata import version
```
correct
```
from importlib_metadata import version
```
Use importlib_metadata (underscore) when you need the backport's newer features or are on Python <3.12. The stdlib importlib.metadata lags behind the PyPI package. They are API-compatible but not interchangeable at the import level.
PackageNotFoundError
```
from importlib_metadata import PackageNotFoundError
```
Always catch this exception when calling version(), metadata(), files(), or requires() to handle packages that are not installed.
entry_points
wrong
```
entry_points()['console_scripts']
```
correct
```
from importlib_metadata import entry_points
eps = entry_points(group='console_scripts')
```
Since v5.0, entry_points() always returns an EntryPoints object, not a dict. Pass group= or name= keyword arguments to filter. Dict-key access on the return value was removed.
packages_distributions
```
from importlib_metadata import packages_distributions
```
Returns a mapping of top-level import package names to distribution names. Useful when you need to resolve an import name to a dist name; not available in older stdlib versions.
Distribution
```
from importlib_metadata import Distribution
dist = Distribution.from_name('pip')
```
Custom finder implementations must subclass Distribution and implement all abstract methods; concrete subclasses that skip abstract methods raise errors since deprecated support was removed.

Quickstart verified last tested: 2026-04-23

Retrieve package version, metadata fields, entry points, and the import-name-to-distribution mapping using the modern importlib_metadata API.

from importlib_metadata import version, metadata, entry_points, packages_distributions, PackageNotFoundError

# Get version string
try:
    ver = version('pip')
    print(f'pip version: {ver}')
except PackageNotFoundError:
    print('pip is not installed')

# Read metadata fields
meta = metadata('pip')
print('Author:', meta['Author-email'])
print('Requires-Python:', meta['Requires-Python'])

# List console_scripts entry points (v5.0+ API)
eps = entry_points(group='console_scripts')
for ep in eps:
    print(f'  {ep.name} -> {ep.value}')

# Map import names to distribution names
pkg_to_dist = packages_distributions()
print('importlib_metadata dist(s):', pkg_to_dist.get('importlib_metadata'))