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.95 runs
installs and imports cleanly · install 0.0s · import 0.064s · 18.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.058s · 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.
Upgrade
Version history
9.0.0latest on PyPI · released Mar 20, 2026
Audit
Dependencies
zipprequiredProvides zipfile.Path overlay used for reading metadata from zip archives on sys.path