UV Debugging Skill

Purpose

This skill provides systematic troubleshooting workflows for common uv (Python package manager) issues, with particular focus on build cache problems, installation discrepancies, and package update issues.

When to Use This Skill

Use this skill when encountering:

• Code changes not appearing after uv tool install
• Discrepancy between uv run <command> and globally installed command
• New files/modules missing from installed package
• "Command not found" after installation
• Stale build cache issues
• Installation mode confusion (editable vs production)

Core Concepts

UV Installation Modes

Production Install:

uv tool install .

• Builds wheel package (cached snapshot)
• Fast to install, slow to update
• Requires reinstall after code changes
• Isolated from source directory

Editable Install:

uv tool install --editable .

• Creates symlinks to source directory
• Changes reflect immediately
• Best for active development
• Less isolated

Local Environment:

uv sync          # Setup environment
uv run <command> # Execute from source

• No global install needed
• Always uses current source code
• Fastest iteration cycle
• Recommended for development

Build Cache Location

Global tool installs:

~/.local/share/uv/tools/<package-name>/

Build artifacts:

build/          - Temporary build files
dist/           - Built wheels (.whl) and source distributions
*.egg-info/     - Package metadata and file manifest

Troubleshooting Workflows

Workflow 1: Code Changes Not Appearing

Symptoms:

• Ran uv tool install . or make install
• Code changes don't appear in installed command
• New files/modules missing

Diagnostic Steps:

1. Verify the discrepancy:

   # Check which version is running
   which <command>
   
   # Test local version
   uv run <command> --help
   
   # Test global version
   <command> --help
   

2. Check for stale build artifacts:

   ls -la build/ dist/ *.egg-info 2>/dev/null
   

3. Identify installation mode:

   # Check if editable install
   ls ~/.local/share/uv/tools/<package>/ | grep -i editable
   

Solutions (in order of preference):

Solution A: Clean and Reinstall (Recommended)

# Remove stale artifacts
rm -rf build/ dist/ *.egg-info

# Force fresh build
uv tool install --force .

# Verify
<command> --help

Solution B: Use Makefile Pattern

install: clean
	uv tool install --force .

clean:
	rm -rf build/ dist/ *.egg-info
	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true

Solution C: Switch to Local Environment

# Setup once
uv sync

# Use for development
uv run <command>

Solution D: Use Editable Mode

uv tool install --editable .

Workflow 2: New Module Not Found

Symptoms:

• Added new Python file (e.g., mypackage/commands/new_cmd.py)
• ModuleNotFoundError or command not recognized
• uv run works but global install doesn't

Root Cause: Wheel package built before new file existed. Package metadata (*.egg-info/RECORD) doesn't list the new file.

Solution:

# 1. Clean build artifacts
rm -rf build/ dist/ *.egg-info

# 2. Reinstall with force
uv tool install --force .

# 3. Verify new module appears
<command> <new-subcommand> --help

Prevention: Add to Makefile:

install: clean
	uv tool install --force .

Workflow 3: Debugging Installation Location

Symptoms:

• Unsure which version is running
• Multiple installations conflict
• Changes not appearing despite reinstall

Diagnostic Commands:

# 1. Check which executable
which <command>

# 2. Check Python import location
python3 -c "import <package>; print(<package>.__file__)"

# 3. List all installations
find ~/.local/share/uv/tools -name "<package>*"

# 4. Check if editable install
cat ~/.local/share/uv/tools/<package>/*/site-packages/*.pth 2>/dev/null

Interpretation:

If which <command> shows:

• ~/.local/share/uv/tools/ → Global uv install
• /usr/local/bin/ → System-wide install (pip)
• <project>/.venv/bin/ → Virtual environment

If .pth file exists → Editable install (points to source)

Workflow 4: Entry Point Not Updating

Symptoms:

• Changed command name or added new subcommand
• Entry point not updating in installed version

Root Cause: Entry points defined in pyproject.toml are baked into wheel at build time.

Solution:

1. Verify entry point definition:

   # Read pyproject.toml
   grep -A 10 "\[project.scripts\]" pyproject.toml
   

2. Clean and rebuild:

   rm -rf build/ dist/ *.egg-info
   uv tool install --force .
   

3. Verify entry points installed:

   ls ~/.local/share/uv/tools/<package>/*/bin/
   

Workflow 5: Dependency Issues

Symptoms:

• Import errors for dependencies
• Version conflicts
• ModuleNotFoundError for installed packages

Diagnostic:

# Check installed dependencies
uv pip list

# Check project dependencies
grep -A 20 "dependencies" pyproject.toml

# Check dependency resolution
uv pip tree

Solution:

# Sync dependencies
uv sync --all-extras

# Or for global install
uv tool install --force --reinstall-package <package> .

Decision Tree

Code changes not appearing?
├─ Does `uv run <cmd>` work?
│  ├─ Yes → Stale build cache
│  │  └─ Solution: rm -rf build/ dist/ *.egg-info && uv tool install --force .
│  └─ No → Code issue, not cache
│     └─ Debug the code itself
│
├─ New file/module missing?
│  └─ Solution: Clean build artifacts and reinstall
│
├─ Entry point not found?
│  └─ Check pyproject.toml [project.scripts], then clean and reinstall
│
└─ Dependency missing?
   └─ Run uv sync or uv tool install --reinstall-package

Best Practices

Development Workflow

Option 1: Local Environment (Recommended)

# Setup once
uv sync

# Develop with instant updates
uv run <command>
uv run pytest

Option 2: Editable Install

# Install once
uv tool install --editable .

# Changes reflect immediately
<command>  # Always uses latest source

Option 3: Production Build with Makefile

# Makefile ensures clean builds
make install

# Reinstall after each change
make install

Testing Installation

Before distributing or deploying:

# 1. Clean environment
rm -rf build/ dist/ *.egg-info

# 2. Production build
uv tool install --force .

# 3. Test from clean shell
<command> --help
<command> <subcommand>

# 4. Verify all entry points
ls ~/.local/share/uv/tools/<package>/*/bin/

Common Mistakes

Mistake 1: Assuming --force Cleans Cache

Wrong:

uv tool install --force .  # Doesn't clean build artifacts!

Right:

rm -rf build/ dist/ *.egg-info
uv tool install --force .

Why: --force reinstalls but may reuse cached wheel from dist/.

Mistake 2: Editing Global Install Directly

Wrong:

# Editing files in ~/.local/share/uv/tools/<package>/
vim ~/.local/share/uv/tools/<package>/.../myfile.py

Right:

# Edit source, then reinstall
vim mypackage/myfile.py
make install

Mistake 3: Mixing Installation Methods

Problem:

uv tool install .           # Production install
# Later...
uv tool install --editable . # Now editable
# Changes behavior unpredictably

Solution: Pick one method and stick with it, or uninstall first:

uv tool uninstall <package>
uv tool install --editable .

Advanced Debugging

Inspecting Wheel Contents

# Build wheel
uv build

# List contents
unzip -l dist/*.whl

# Extract and examine
unzip dist/*.whl -d /tmp/wheel-inspect
ls -la /tmp/wheel-inspect/<package>/

Checking Package Metadata

# View installed package info
uv pip show <package>

# View RECORD file (manifest of installed files)
cat ~/.local/share/uv/tools/<package>/*/*.dist-info/RECORD

Debugging Import Paths

import sys
print("Python path:")
for p in sys.path:
    print(f"  {p}")

import <package>
print(f"\nPackage location: {<package>.__file__}")

Reference: Build Process

Understanding what happens during uv tool install .:

1. Read metadata - Parse pyproject.toml for package info
2. Collect files - Find all Python files in package
3. Build wheel - Create .whl in dist/
4. Write manifest - Record all files in *.egg-info/RECORD
5. Install wheel - Copy to ~/.local/share/uv/tools/<package>/
6. Create entry points - Generate executables in bin/

Key insight: Steps 3-4 create a snapshot. New files added after this won't be included until rebuild.

Quick Reference

Check what's running:

which <command>
uv run <command> --version
<command> --version

Clean build cache:

rm -rf build/ dist/ *.egg-info

Fresh install:

uv tool install --force .

Development mode:

uv sync && uv run <command>

Inspect installation:

ls ~/.local/share/uv/tools/<package>/
uv pip show <package>

Official UV Documentation

Cache Management:

• https://docs.astral.sh/uv/concepts/cache/ - How UV caches packages, cache types, cache location, cache commands

Build Troubleshooting:

• https://docs.astral.sh/uv/reference/troubleshooting/build-failures/ - Common build errors, missing dependencies, build isolation issues

CLI Commands:

• https://docs.astral.sh/uv/reference/cli/ - Complete command reference with all flags and options

Settings Reference:

• https://docs.astral.sh/uv/reference/settings/ - Configuration options for build constraints, cache control, dependency resolution

Internal References

For deep technical details, see:

• references/python-build-cache.md - Why Python build cache doesn't auto-update
• references/uv-cli-reference.md - UV command workflows and examples

Troubleshooting Checklist

When encountering issues:

• Does uv run <command> work? (Rules out code issues)
• Are there stale artifacts in build/, dist/, *.egg-info?
• Which installation mode am I using? (production/editable/local)
• Did I recently add new files?
• Did I update pyproject.toml dependencies or entry points?
• Am I using the right which <command> version?
• Have I tried cleaning and reinstalling?

Exit Codes

Common uv exit codes:

• 0 - Success
• 1 - General error
• 2 - Command line usage error
• 101 - Package not found
• 102 - Version conflict