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.
Install & Compatibility
Where this runs
tested against v9.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 0.065s · 18.1MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 1.6s · import 0.060s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
version
✓ from importlib_metadata import 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')
✗ entry_points()['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.
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'))
Debug
Known issues
breakingentry_points() no longer returns a dict. Since v5.0 it always returns an EntryPoints object. Code like entry_points()['console_scripts'] raises a TypeError.fixUse entry_points(group='console_scripts') to filter by group, or iterate the returned EntryPoints object directly.
affects: <5.0
breakingEntryPoint objects lost their tuple-like interface (__getitem__). Code that unpacked EntryPoints as tuples (e.g. name, ep = entry_point) fails silently or raises TypeError.fixAccess entry point attributes by name: ep.name, ep.value, ep.group. Call ep.load() to import the target.
affects: corresponds to Python 3.13 / importlib_metadata 7+
breakingmetadata(pkg)['Missing-Key'] now raises KeyError instead of returning None. Previously absent keys silently returned None.fixUse metadata(pkg).get('Missing-Key') or wrap access in a try/except KeyError. affects: >=7.0
breakingDistribution subclasses that do not implement all abstract methods now raise errors. Deprecated compatibility shim was removed.fixImplement all abstract methods (read_text, locate_file) when subclassing Distribution for custom finders.
affects: >=7.0
gotchaversion() 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.fixUse packages_distributions() to map an import name to its distribution name before calling version() or metadata().
affects: all
gotchaimportlib_metadata does not support stdlib modules or packages installed without dist-info/egg-info metadata. Calling version('os') raises PackageNotFoundError.fixAlways catch PackageNotFoundError. For editable/local installs ensure the package was installed with pip install -e . so metadata is written.
affects: all
deprecatedOn 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.fixCheck the stdlib/backport version correspondence table on PyPI before adding importlib-metadata as a hard dependency in projects targeting Python >=3.12.
affects: all
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'importlib_metadata'
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.
fixInstall the 'importlib-metadata' package using pip: `pip install importlib-metadata`
ModuleNotFoundError: No module named 'importlib.metadata'
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.
fixFor 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.
AttributeError: module 'importlib_metadata' has no attribute 'EntryPoints'
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.
fixUpgrade the `importlib-metadata` package to its latest version: `pip install --upgrade importlib-metadata`.
TypeError: entry_points() got an unexpected keyword argument 'group'
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`.
fixUpgrade 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.
Audit
Dependencies
zipprequiredProvides zipfile.Path overlay used for reading metadata from zip archives on sys.path