Python "pkg_resources is deprecated" Fails Builds Under -W error

Recent setuptools emits a DeprecationWarning (sometimes UserWarning) when pkg_resources is imported. On a job that promotes warnings to errors, that import - often inside a dependency - turns into a hard failure.

What this error means

A run that sets -W error or filterwarnings = error fails with DeprecationWarning: pkg_resources is deprecated as an API, pointing at an import pkg_resources somewhere in your stack. Without warnings-as-errors it is only a noisy log line.

Python traceback

DeprecationWarning: pkg_resources is deprecated as an API. See
https://setuptools.pypa.io/en/latest/pkg_resources.html
  import pkg_resources

Common causes

A dependency still imports pkg_resources

setuptools now deprecates the pkg_resources runtime API. A library you depend on still imports it, so the warning fires from inside that package.

Warnings promoted to errors

A strict -W error/filterwarnings = error config turns the deprecation into an exception, failing the otherwise-working job.

How to fix it

Migrate your own code to importlib.metadata

If the import is in your code, replace pkg_resources with the stdlib importlib.metadata/importlib.resources.

Python

# was: import pkg_resources; v = pkg_resources.get_distribution("x").version
from importlib.metadata import version
v = version("x")

Scope the warning filter to the offending module

When the import is inside a third-party package you cannot change yet, ignore that specific deprecation rather than disabling all warnings-as-errors.

pyproject.toml

[tool.pytest.ini_options]
filterwarnings = [
  "error",
  "ignore:pkg_resources is deprecated:DeprecationWarning",
]

How to prevent it

Prefer importlib.metadata/importlib.resources over pkg_resources.
Scope warning filters narrowly instead of disabling strict mode.
Track dependency upgrades that drop pkg_resources usage.