Initial commit
This commit is contained in:
Zhongwei Li
500
skills/uv-debug/SKILL.md
Normal file
500
skills/uv-debug/SKILL.md
Normal file
@@ -0,0 +1,500 @@
|
||||
---
|
||||
name: uv-debug
|
||||
description: Troubleshooting and debugging problems with uv (Python package manager). Use when encountering uv installation issues, stale build cache, package not updating, or discrepancies between uv run and global installs.
|
||||
---
|
||||
|
||||
# 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:**
|
||||
```bash
|
||||
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:**
|
||||
```bash
|
||||
uv tool install --editable .
|
||||
```
|
||||
- Creates symlinks to source directory
|
||||
- Changes reflect immediately
|
||||
- Best for active development
|
||||
- Less isolated
|
||||
|
||||
**Local Environment:**
|
||||
```bash
|
||||
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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
ls -la build/ dist/ *.egg-info 2>/dev/null
|
||||
```
|
||||
|
||||
3. **Identify installation mode:**
|
||||
```bash
|
||||
# Check if editable install
|
||||
ls ~/.local/share/uv/tools/<package>/ | grep -i editable
|
||||
```
|
||||
|
||||
**Solutions (in order of preference):**
|
||||
|
||||
**Solution A: Clean and Reinstall (Recommended)**
|
||||
```bash
|
||||
# Remove stale artifacts
|
||||
rm -rf build/ dist/ *.egg-info
|
||||
|
||||
# Force fresh build
|
||||
uv tool install --force .
|
||||
|
||||
# Verify
|
||||
<command> --help
|
||||
```
|
||||
|
||||
**Solution B: Use Makefile Pattern**
|
||||
```makefile
|
||||
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**
|
||||
```bash
|
||||
# Setup once
|
||||
uv sync
|
||||
|
||||
# Use for development
|
||||
uv run <command>
|
||||
```
|
||||
|
||||
**Solution D: Use Editable Mode**
|
||||
```bash
|
||||
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:**
|
||||
```bash
|
||||
# 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:
|
||||
```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:**
|
||||
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
# Read pyproject.toml
|
||||
grep -A 10 "\[project.scripts\]" pyproject.toml
|
||||
```
|
||||
|
||||
2. **Clean and rebuild:**
|
||||
```bash
|
||||
rm -rf build/ dist/ *.egg-info
|
||||
uv tool install --force .
|
||||
```
|
||||
|
||||
3. **Verify entry points installed:**
|
||||
```bash
|
||||
ls ~/.local/share/uv/tools/<package>/*/bin/
|
||||
```
|
||||
|
||||
### Workflow 5: Dependency Issues
|
||||
|
||||
**Symptoms:**
|
||||
- Import errors for dependencies
|
||||
- Version conflicts
|
||||
- `ModuleNotFoundError` for installed packages
|
||||
|
||||
**Diagnostic:**
|
||||
|
||||
```bash
|
||||
# Check installed dependencies
|
||||
uv pip list
|
||||
|
||||
# Check project dependencies
|
||||
grep -A 20 "dependencies" pyproject.toml
|
||||
|
||||
# Check dependency resolution
|
||||
uv pip tree
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
|
||||
```bash
|
||||
# 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)**
|
||||
```bash
|
||||
# Setup once
|
||||
uv sync
|
||||
|
||||
# Develop with instant updates
|
||||
uv run <command>
|
||||
uv run pytest
|
||||
```
|
||||
|
||||
**Option 2: Editable Install**
|
||||
```bash
|
||||
# Install once
|
||||
uv tool install --editable .
|
||||
|
||||
# Changes reflect immediately
|
||||
<command> # Always uses latest source
|
||||
```
|
||||
|
||||
**Option 3: Production Build with Makefile**
|
||||
```bash
|
||||
# Makefile ensures clean builds
|
||||
make install
|
||||
|
||||
# Reinstall after each change
|
||||
make install
|
||||
```
|
||||
|
||||
### Testing Installation
|
||||
|
||||
Before distributing or deploying:
|
||||
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
uv tool install --force . # Doesn't clean build artifacts!
|
||||
```
|
||||
|
||||
**Right:**
|
||||
```bash
|
||||
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:**
|
||||
```bash
|
||||
# Editing files in ~/.local/share/uv/tools/<package>/
|
||||
vim ~/.local/share/uv/tools/<package>/.../myfile.py
|
||||
```
|
||||
|
||||
**Right:**
|
||||
```bash
|
||||
# Edit source, then reinstall
|
||||
vim mypackage/myfile.py
|
||||
make install
|
||||
```
|
||||
|
||||
### Mistake 3: Mixing Installation Methods
|
||||
|
||||
**Problem:**
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
uv tool uninstall <package>
|
||||
uv tool install --editable .
|
||||
```
|
||||
|
||||
## Advanced Debugging
|
||||
|
||||
### Inspecting Wheel Contents
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```python
|
||||
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:**
|
||||
```bash
|
||||
which <command>
|
||||
uv run <command> --version
|
||||
<command> --version
|
||||
```
|
||||
|
||||
**Clean build cache:**
|
||||
```bash
|
||||
rm -rf build/ dist/ *.egg-info
|
||||
```
|
||||
|
||||
**Fresh install:**
|
||||
```bash
|
||||
uv tool install --force .
|
||||
```
|
||||
|
||||
**Development mode:**
|
||||
```bash
|
||||
uv sync && uv run <command>
|
||||
```
|
||||
|
||||
**Inspect installation:**
|
||||
```bash
|
||||
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
|
||||
Reference in New Issue
Block a user