**Source code:** :source:`Lib/importlib/metadata/__init__.py`

``importlib_metadata`` is a library that provides access to

the metadata of an installed `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_,

such as its entry points

or its top-level names (`Import Package <https://packaging.python.org/en/latest/glossary/#term-Import-Package>`_\s, modules, if any).

Built in part on Python's import system, this library

intends to replace similar functionality in the `entry point

API`_ and `metadata API`_ of ``pkg_resources``. Along with

`pip <https://pypi.org/project/pip/>`_.

Specifically, it works with distributions with discoverable

``dist-info`` or ``egg-info`` directories,

and metadata defined by the `Core metadata specifications <https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata>`_.

.. important::

Let's say you wanted to get the version string for a

`Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_ you've installed

using ``pip``. We start by creating a virtual environment and installing

something into it:

Distribution metadata

Every `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_ includes some metadata,

which you can extract using the

``metadata()`` function::

The ``version()`` function is the quickest way to get a

`Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_'s version

number, as a string::

You can also get the full set of files contained within a distribution. The

``files()`` function takes a `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_ name

and returns all of the

files installed by this distribution. Each file object returned is a

``PackagePath``, a :class:`pathlib.PurePath` derived object with additional ``dist``,

Distribution requirements

To get the full set of requirements for a `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_,

use the ``requires()``

function::

Mapping import to distribution packages

A convenience method to resolve the `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_

name (or names, in the case of a namespace package)

that provide each importable top-level

Python module or `Import Package <https://packaging.python.org/en/latest/glossary/#term-Import-Package>`_::

While the above API is the most common and convenient usage, you can get all

of that information from the ``Distribution`` class. A ``Distribution`` is an

abstract object that represents the metadata for

a Python `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_. You can

get the ``Distribution`` instance::

The full set of available metadata is not described here.

See the `Core metadata specifications <https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata>`_ for additional details.

Distribution Discovery

By default, this package provides built-in support for discovery of metadata

for file system and zip file `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_\s.

This metadata finder search defaults to ``sys.path``, but varies slightly in how it interprets those values from how other import machinery does. In particular:

- ``importlib.metadata`` does not honor :class:`bytes` objects on ``sys.path``.

Extending the search algorithm

Because `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_ metadata

is not available through :data:`sys.path` searches, or

package loaders directly,

the metadata for a distribution is found through import