| name | uv-debug |
| description | Troubleshooting uv (Python package manager) issues - stale cache, installation problems, package updates. |
UV Debugging
Installation Modes
| Mode | Command | Updates | Best For |
|---|
| Production | uv tool install . | Requires reinstall | Distribution |
| Editable | uv tool install --editable . | Immediate | Active dev |
| Local | uv sync + uv run <cmd> | Immediate | Recommended |
Cache Locations
~/.local/share/uv/tools/<package>/ # Global installs
build/ dist/ *.egg-info/ # Build artifacts (source of problems!)
Code Changes Not Appearing?
Decision Tree:
Does `uv run <cmd>` work?
├─ Yes → Stale build cache → Clean and reinstall
└─ No → Code issue, not cache
The Fix (90% of cases):
rm -rf build/ dist/ *.egg-info
uv tool install --force .
Diagnostic:
which <command>
uv run <command> --help
ls -la build/ dist/ *.egg-info
Common Mistakes
--force doesn't clean cache!
uv tool install --force .
rm -rf build/ dist/ *.egg-info && uv tool install --force .
Makefile pattern
install: clean
uv tool install --force .
clean:
rm -rf build/ dist/ *.egg-info
New Module Not Found?
Wheel was built before file existed.
rm -rf build/ dist/ *.egg-info
uv tool install --force .
Entry Point Not Updating?
Entry points baked into wheel at build time.
grep -A 10 "\[project.scripts\]" pyproject.toml
rm -rf build/ dist/ *.egg-info
uv tool install --force .
ls ~/.local/share/uv/tools/<package>/*/bin/
Debug Installation Location
which <command>
python3 -c "import <pkg>; print(<pkg>.__file__)"
find ~/.local/share/uv/tools -name "<package>*"
cat ~/.local/share/uv/tools/<pkg>/*/site-packages/*.pth
Quick Reference
which <cmd> && uv run <cmd> --version && <cmd> --version
rm -rf build/ dist/ *.egg-info && uv tool install --force .
uv sync && uv run <command>
ls ~/.local/share/uv/tools/<package>/
uv pip show <package>
Docs