Python "pkg_resources.ContextualVersionConflict" in CI

At runtime, pkg_resources found a dependency installed at a version that does not satisfy what another package requires. The environment installed, but the resolved versions are inconsistent.

What this error means

A program fails at startup with pkg_resources.ContextualVersionConflict: (pkg X.Y (...), Requirement.parse('pkg>=Z'), {...}). The environment has the package, but the wrong version for what a consumer demands.

Python traceback

pkg_resources.ContextualVersionConflict: (urllib3 2.2.1
(/venv/lib/python3.12/site-packages),
Requirement.parse('urllib3<2'), {'botocore'})

Common causes

An installed version violates a runtime requirement

A package requires urllib3<2 but the environment has urllib3 2.x. pip’s resolver may not have caught it if packages were installed in separate steps.

Piecemeal installs bypassed the resolver

Installing packages one at a time (or with --no-deps) can leave versions that pip would never have resolved together, surfacing only when pkg_resources checks at runtime.

How to fix it

Resolve everything together

Install all requirements in one pip invocation so the resolver picks a consistent set.

Terminal

pip install -r requirements.txt   # one resolve, not many
pip check                          # report inconsistent versions

Pin the conflicting dependency correctly

Align the shared package to a version every consumer accepts.

requirements.txt

# botocore needs urllib3<2 on this Python
urllib3>=1.25.4,<2

How to prevent it

Install all requirements in a single resolve; avoid piecemeal --no-deps.
Run pip check in CI to catch inconsistent environments early.
Use a lockfile so the installed set is internally consistent.