VVersions.dev

Fix Python dependency errors

Most Python dependency errors come from a polluted environment or conflicting version constraints. Reproduce in a clean venv, read the resolver output, and pin deliberately rather than guessing.

WorkflowDifficulty: moderatemedium risk

Last verified · Updated May 22, 2026

Dependency errors almost always trace to a polluted environment or incompatible version constraints. Reproduce in a fresh venv, read pip's resolver output carefully, and pin deliberately — do not blindly --force-reinstall or upgrade everything at once.

Symptoms

  • ERROR: ResolutionImpossible / cannot install because these package versions have conflicting dependencies.
  • ModuleNotFoundError despite the package appearing installed.
  • error: command 'gcc' failed — a C extension failed to build from source.
  • Behavior that differs between machines or between local and CI.

Likely causes

  • Installing into the system or a stale virtualenv instead of a clean venv.
  • Conflicting transitive version constraints the resolver cannot satisfy.
  • requirements.txt drift from an actual lockfile.
  • Missing build toolchain or no prebuilt wheel for the platform/interpreter.

Diagnostic commands

shell
# Reproduce in a clean, isolated environment$ python -m venv .venv && . .venv/bin/activate$ pip install -e .$ pip check                    # surface broken/conflicting requirements$ pip install --upgrade pip    # an old resolver causes false conflicts
Test failure debuggingAI debugging prompt
pip is failing to install dependencies for this project. Here is the full error and the requirements/pyproject: <paste>. Reproduce in a clean venv, identify whether this is a resolver conflict, a missing wheel/build-toolchain issue, or environment pollution, and propose the smallest set of version pins that resolves it. Explain which constraint forced the conflict before suggesting any change.

Safety: Do not --force-reinstall or blanket --upgrade to mask a conflict; identify the conflicting constraint first.

Safe fix workflow

  • Recreate a clean venv and reproduce the error in isolation.
  • Run pip check and read which constraint pair conflicts.
  • Pin the minimal set of versions that resolves it; record them in the lockfile.
  • For build failures, install the platform toolchain or pin a version with a prebuilt wheel.

Escalation checklist

  • Conflict persists in a clean venv with the latest pip
  • A required dependency has no wheel for the target Python/platform
  • requirements.txt and the lockfile disagree on a pinned version

Related upgrade pages

Official sources