{"id":275,"library":"importlib-metadata","title":"importlib-metadata","description":"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.","status":"active","version":"9.0.0","language":"python","source_language":"en","source_url":"https://github.com/python/importlib_metadata","tags":["packaging","metadata","introspection","entry-points","stdlib-backport"],"install":[{"cmd":"pip install importlib-metadata","lang":"bash","label":"Latest (PyPI)"}],"dependencies":[{"reason":"Provides zipfile.Path overlay used for reading metadata from zip archives on sys.path","package":"zipp","optional":false}],"imports":[{"note":"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.","wrong":"from importlib.metadata import version","symbol":"version","correct":"from importlib_metadata import version"},{"note":"Always catch this exception when calling version(), metadata(), files(), or requires() to handle packages that are not installed.","symbol":"PackageNotFoundError","correct":"from importlib_metadata import PackageNotFoundError"},{"note":"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.","wrong":"entry_points()['console_scripts']","symbol":"entry_points","correct":"from importlib_metadata import entry_points\neps = entry_points(group='console_scripts')"},{"note":"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.","symbol":"packages_distributions","correct":"from importlib_metadata import packages_distributions"},{"note":"Custom finder implementations must subclass Distribution and implement all abstract methods; concrete subclasses that skip abstract methods raise errors since deprecated support was removed.","symbol":"Distribution","correct":"from importlib_metadata import Distribution\ndist = Distribution.from_name('pip')"}],"quickstart":{"code":"from importlib_metadata import version, metadata, entry_points, packages_distributions, PackageNotFoundError\n\n# Get version string\ntry:\n    ver = version('pip')\n    print(f'pip version: {ver}')\nexcept PackageNotFoundError:\n    print('pip is not installed')\n\n# Read metadata fields\nmeta = metadata('pip')\nprint('Author:', meta['Author-email'])\nprint('Requires-Python:', meta['Requires-Python'])\n\n# List console_scripts entry points (v5.0+ API)\neps = entry_points(group='console_scripts')\nfor ep in eps:\n    print(f'  {ep.name} -> {ep.value}')\n\n# Map import names to distribution names\npkg_to_dist = packages_distributions()\nprint('importlib_metadata dist(s):', pkg_to_dist.get('importlib_metadata'))\n","lang":"python","description":"Retrieve package version, metadata fields, entry points, and the import-name-to-distribution mapping using the modern importlib_metadata API."},"warnings":[{"fix":"Use entry_points(group='console_scripts') to filter by group, or iterate the returned EntryPoints object directly.","message":"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.","severity":"breaking","affected_versions":"<5.0"},{"fix":"Access entry point attributes by name: ep.name, ep.value, ep.group. Call ep.load() to import the target.","message":"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.","severity":"breaking","affected_versions":"corresponds to Python 3.13 / importlib_metadata 7+"},{"fix":"Use metadata(pkg).get('Missing-Key') or wrap access in a try/except KeyError.","message":"metadata(pkg)['Missing-Key'] now raises KeyError instead of returning None. Previously absent keys silently returned None.","severity":"breaking","affected_versions":">=7.0"},{"fix":"Implement all abstract methods (read_text, locate_file) when subclassing Distribution for custom finders.","message":"Distribution subclasses that do not implement all abstract methods now raise errors. Deprecated compatibility shim was removed.","severity":"breaking","affected_versions":">=7.0"},{"fix":"Use packages_distributions() to map an import name to its distribution name before calling version() or metadata().","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Always catch PackageNotFoundError. For editable/local installs ensure the package was installed with pip install -e . so metadata is written.","message":"importlib_metadata does not support stdlib modules or packages installed without dist-info/egg-info metadata. Calling version('os') raises PackageNotFoundError.","severity":"gotcha","affected_versions":"all"},{"fix":"Check the stdlib/backport version correspondence table on PyPI before adding importlib-metadata as a hard dependency in projects targeting Python >=3.12.","message":"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.","severity":"deprecated","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-12T12:44:47.597Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Install the 'importlib-metadata' package using pip: `pip install 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.","error":"ModuleNotFoundError: No module named 'importlib_metadata'"},{"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.","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.","error":"ModuleNotFoundError: No module named 'importlib.metadata'"},{"fix":"Upgrade the `importlib-metadata` package to its latest version: `pip install --upgrade importlib-metadata`.","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.","error":"AttributeError: module 'importlib_metadata' has no attribute 'EntryPoints'"},{"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.","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`.","error":"TypeError: entry_points() got an unexpected keyword argument 'group'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":null,"cli_name":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2.1,"disk_size":"18.1M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":2.1,"disk_size":"19M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.09,"mem_mb":2.5,"disk_size":"20.0M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.5,"disk_size":"20M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.09,"mem_mb":3.2,"disk_size":"11.8M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":3.2,"disk_size":"12M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.08,"mem_mb":3,"disk_size":"11.5M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.9,"disk_size":"12M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2,"disk_size":"17.6M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2,"disk_size":"18M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}