Debug: Python package conflicts and dependency resolution

pip install fails with version conflicts, or packages break after installing a new dependency.

Diagnose and resolve Python dependency conflicts:

# 1. See what's installed and check for conflicts
pip check  # Reports incompatible packages
pip list   # All installed packages with versions

# 2. See dependency tree
pip install pipdeptree
pipdeptree  # Full tree
pipdeptree -r -p requests  # Reverse: who depends on requests?

# 3. See why a specific version was installed
pip show numpy  # Shows required-by

# 4. Common resolution strategies:

# Strategy 1: Fresh venv (cleanest)
deactivate
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Strategy 2: Use pip-tools for deterministic resolution
pip install pip-tools
# requirements.in (what you want):
# django>=4.2
# celery>=5.3
pip-compile requirements.in  # Resolves and pins all deps
pip-sync requirements.txt    # Install exactly these versions

# Strategy 3: Use uv (faster, better resolver)
pip install uv
uv pip compile requirements.in -o requirements.txt
uv pip sync requirements.txt

# Strategy 4: Override specific version
pip install 'numpy>=1.24,<2.0'  # Constrain version range

# 5. For complex conflicts: check the error message
# "X requires Y>=2.0, but you have Y 1.9"
# -> Either upgrade Y or find a version of X compatible with Y 1.9
pip install 'X<3.0'  # Try older X that works with Y 1.9

Prevention:

• Always use virtual environments
• Pin dependencies with pip-compile
• Update dependencies regularly (small increments)
• Use pip install --dry-run to preview changes

Python's dependency resolution is notoriously complex. pip-tools and uv provide deterministic resolution, preventing 'works on my machine' issues.

Python projects with dependency management issues