Migration guide#

The following guide will help you migrate common pkg_resources APIs to importlib_metadata. importlib_metadata aims to replace the following pkg_resources APIs:

  • pkg_resources.iter_entry_points()

  • pkg_resources.require()

  • convenience functions

  • pkg_resources.find_distributions()

  • pkg_resources.get_distribution()

Other functionality from pkg_resources is replaced by other packages such as importlib_resources and packaging.

pkg_resources.iter_entry_points()#

importlib_metadata provides Entry points.

Compatibility note: entry points provided by importlib_metadata do not have the following implicit behaviors found in those from pkg_resources:

  • Each EntryPoint is not automatically validated to match. To ensure each one is validated, invoke any property on the object (e.g. ep.name).

  • When invoking EntryPoint.load(), no checks are performed to ensure the declared extras are installed. If this behavior is desired/required, it is left to the user to perform the check and install any dependencies. See importlib_metadata#368 for more details.

pkg_resources.require()#

importlib_metadata does not provide support for dynamically discovering or requiring distributions nor does it provide any support for managing the “working set”. Furthermore, importlib_metadata assumes that only one version of a given distribution is discoverable at any time (no support for multi-version installs). Any projects that require the above behavior needs to provide that behavior independently.

importlib_metadata does aim to resolve metadata concerns late such that any dynamic changes to package availability should be reflected immediately.

Convenience functions#

In addition to the support for direct access to Distribution objects (below), importlib_metadata presents some top-level functions for easy access to the most common metadata:

pkg_resources.find_distributions()#

importlib_metadata provides functionality similar to find_distributions(). Both distributions(...) and Distribution.discover(...) return an iterable of Distributions matching the indicated parameters.

pkg_resources.get_distribution()#

Similar to distributions, the distribution() function provides access to a single distribution by name.