Dependency pitfalls

Use this reference to explain the doctor's findings without overstating them. The script identifies focused manifest problems. It does not replace a resolver or vulnerability database.

Standard-library shadowing

A requirement can have the same name as a Python standard-library module. Pip then places a separately maintained distribution on the import path, where it can shadow or conflict with the runtime's own module.

Two concrete examples:

pathlib==1.0.1
dataclasses

pathlib has shipped with Python since 3.4. The old PyPI backport should not be installed on modern Python. dataclasses has shipped with Python since 3.7; its backport exists for Python 3.6. On supported modern runtimes, remove these lines and import the standard-library modules directly.

When a project intentionally supports an older Python release, use an explicit environment marker instead of installing the backport everywhere. Confirm the project's supported Python range before editing.

Abandoned and obsolete backports

Backports such as typing, enum34, futures, and singledispatch solved real gaps in older Python versions. They become liabilities when pinned for runtimes that already provide the feature. They may be unmaintained, constrain other packages, or expose an implementation that no longer matches the standard library.

The right fix is usually removal. If an old runtime remains supported, add a Python-version marker and test both sides of the marker.

Yanked releases

PyPI can mark release files as yanked when a version is broken, unsafe, or published by mistake. Yanked files remain available so existing exact pins can still resolve, which means an old manifest may keep installing a bad release.

The doctor's online check is deliberately opt-in. It queries only exact pins and reports a release as yanked only when every file for that version is marked yanked. A yank is not automatically a CVE, and a CVE does not require a yank. Use a dedicated security scanner for vulnerability coverage.

Pin hygiene

A bare dependency such as requests can resolve differently on two machines or two dates. Before creating an exact pin:

1. Inspect the version installed in the project's working environment.
2. Confirm that version is intentional and supported.
3. Run the project's tests with the proposed pin.
4. Preserve environment markers and extras from the original requirement.

Do not invent a version from memory. Lockfiles and constraint files may already be the project's chosen source of reproducibility, so inspect them before changing a manifest.

Duplicates and conflicts

Identical repeated lines create two places to maintain one decision. Compatible ranges on separate lines can usually be combined. Different exact pins, such as urllib3==1.26.18 and urllib3==2.2.2, cannot both be satisfied and require a deliberate version choice.

Before resolving a conflict, inspect which direct dependency introduced each constraint. Choosing the newest number without checking dependents can turn a clear resolver failure into a runtime regression.