importlib-metadata

9.0.0 · active · verified Sat Mar 28

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.

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

pip install importlib-metadata Latest (PyPI)

Imports

version
```
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
```
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

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'))

view raw JSON →