zhongwei/gh-warrenzhu050413-warren-claude-code-plugin-marketplace-claude-context-orchestrator

Fork 0

Files

Zhongwei Li 09fec2555b Initial commit

2025-11-30 09:05:19 +08:00

11 KiB

Raw Permalink Blame History

UV CLI Reference for Troubleshooting

Overview

This reference covers UV commands and flags commonly used for troubleshooting package installation and build issues.

Cache Management

uv cache clean

Remove all or specific cache entries:

# Remove ALL cache entries
uv cache clean

# Remove cache for specific package
uv cache clean <package-name>

# Example: Clean numpy cache
uv cache clean numpy

When to use:

Suspected stale cache causing installation issues
After manually editing cache (not recommended)
When builds succeed locally but fail in CI

uv cache prune

Remove unused cache entries:

# Remove all unused cache entries
uv cache prune

# CI-optimized: Remove pre-built wheels, keep source-built wheels
uv cache prune --ci

When to use:

Disk space optimization
CI pipelines (use --ci flag)
After resolving dependency conflicts

Difference from clean:

clean: Removes everything (or specific package)
prune: Removes only unused entries
prune --ci: Keeps wheels built from source

Cache Refresh Options

--refresh

Force revalidation of all cached data:

# Refresh all dependencies
uv sync --refresh

# Refresh during install
uv pip install --refresh <package>

# Refresh tool installation
uv tool install --refresh <package>

When to use:

After package update on PyPI
Suspected outdated cached metadata
Testing with latest available versions

--refresh-package

Target specific package for revalidation:

# Refresh only numpy
uv sync --refresh-package numpy

# Refresh multiple packages
uv sync --refresh-package numpy --refresh-package pandas

When to use:

Know specific package is outdated
Avoid full cache revalidation overhead
Testing specific package update

--reinstall

Ignore existing installed versions:

# Reinstall everything
uv sync --reinstall

# Reinstall specific package
uv pip install --reinstall <package>

When to use:

Installation corrupted
Different version needed
Testing clean installation

Difference from --refresh:

--refresh: Revalidates cache, may reuse if valid
--reinstall: Forces fresh installation regardless

Build Isolation Control

--no-build-isolation-package

Disable build isolation for specific packages:

# Disable isolation for one package
uv pip install --no-build-isolation-package chumpy chumpy

# Disable for multiple packages
uv pip install --no-build-isolation-package pkg1 --no-build-isolation-package pkg2 pkg1 pkg2

When to use:

Package build script needs system dependencies
Import errors during build
Build backend requires pre-installed modules

Prerequisite: Install build dependencies first:

uv pip install pip setuptools wheel
uv pip install --no-build-isolation-package <package> <package>

--no-build-isolation

Disable build isolation globally:

uv pip install --no-build-isolation <package>

When to use:

Multiple packages need system access
Testing build with system packages
Legacy packages with non-standard builds

Installation Options

--force

Force reinstallation (for uv tool):

# Force tool reinstall
uv tool install --force <package>

# Force tool reinstall with editable mode
uv tool install --force --editable .

When to use:

Tool already installed, need to update
Switching between editable/production modes
After source code changes (non-editable mode)

--editable

Install in editable mode:

# Install current directory as editable
uv tool install --editable .

# Install specific package as editable
uv pip install --editable /path/to/package

When to use:

Active development
Changes need to reflect immediately
No reinstall after code modifications

--reinstall-package

Reinstall specific package:

# Reinstall numpy only
uv sync --reinstall-package numpy

# Reinstall multiple packages
uv sync --reinstall-package numpy --reinstall-package pandas

When to use:

Specific package corrupted
Version conflict resolution
After dependency update

Build Configuration

--build-constraint

Constrain build dependencies:

# Set build constraints via config
# In pyproject.toml:
[tool.uv]
build-constraint-dependencies = ["setuptools<70"]

# Or via environment
UV_BUILD_CONSTRAINT_DEPENDENCIES="setuptools<70" uv pip install <package>

When to use:

Outdated build dependencies causing failures
Known incompatible build dependency versions
Reproducible build environments

--constraint

Apply version constraints during resolution:

# Via file
uv pip install -c constraints.txt <package>

# Via config
# In pyproject.toml:
[tool.uv]
constraint-dependencies = ["numpy<2.0"]

When to use:

Enforcing maximum versions
Preventing incompatible upgrades
Corporate policy requirements

Diagnostic Commands

uv pip show

Display package information:

# Show installed package details
uv pip show <package>

# Output includes: version, location, dependencies

When to use:

Verify installation location
Check installed version
Inspect dependencies

uv pip list

List installed packages:

# List all packages
uv pip list

# JSON output
uv pip list --format json

When to use:

Audit installed packages
Check for duplicates
Compare environments

uv pip tree

Show dependency tree:

# Full dependency tree
uv pip tree

# Reverse tree (who depends on this package)
uv pip tree --reverse <package>

When to use:

Understand dependency relationships
Find dependency conflicts
Trace transitive dependencies

Environment Management

uv venv

Create virtual environment:

# Create with system Python
uv venv

# Create with specific Python version
uv venv -p 3.13

# Create with seed packages (pip, setuptools, wheel)
uv venv --seed

When to use:

Isolate project dependencies
Test different Python versions
Reproduce CI environment

uv sync

Synchronize environment with lock file:

# Basic sync
uv sync

# Include all extras
uv sync --all-extras

# Development dependencies only
uv sync --dev-only

When to use:

After updating pyproject.toml
Setting up development environment
Syncing team dependencies

Tool Management

uv tool install

Install command-line tools:

# Basic install
uv tool install <package>

# With extras
uv tool install "package[extra1,extra2]"

# Specific version
uv tool install package==1.0.0

uv tool uninstall

Remove installed tools:

# Uninstall tool
uv tool uninstall <package>

When to use:

Before switching installation modes
Cleaning up old versions
Resolving tool conflicts

uv tool list

List installed tools:

# Show all tools
uv tool list

# Include package versions
uv tool list --verbose

Run Commands

uv run

Execute command in project environment:

# Run Python script
uv run python script.py

# Run package entry point
uv run <command>

# Run with specific Python
uv run -p 3.13 <command>

When to use:

Development without global install
Testing before installation
Avoiding installation cache issues

Debug Flags

--verbose

Enable verbose logging:

# Show detailed operations
uv pip install --verbose <package>

# Abbreviated form
uv pip install -v <package>

When to use:

Diagnosing installation issues
Understanding resolution decisions
Reporting bugs

--debug

Enable debug logging:

# Maximum verbosity
uv pip install --debug <package>

When to use:

Deep troubleshooting
Network issues
Cache problems

--no-cache

Disable cache for operation:

# Install without using cache
uv pip install --no-cache <package>

When to use:

Verifying cache isn't the problem
Testing clean installation
CI reproducibility checks

Cache Location Control

--cache-dir

Specify cache directory:

# Use custom cache location
uv pip install --cache-dir /tmp/uv-cache <package>

# Via environment variable
UV_CACHE_DIR=/tmp/uv-cache uv pip install <package>

When to use:

CI with custom cache storage
Testing cache behavior
Shared team cache

Common Troubleshooting Workflows

Workflow 1: Resolve Build Failure

# 1. Identify if UV-specific
uv venv -p 3.13 --seed
source .venv/bin/activate
pip install --use-pep517 --no-cache --force-reinstall 'package==version'

# 2. If pip fails too, install build dependencies
apt install build-essential  # Ubuntu/Debian
# or
brew install gcc  # macOS

# 3. Try again with UV
uv pip install <package>

# 4. If still fails, disable build isolation
uv pip install pip setuptools
uv pip install --no-build-isolation-package <package> <package>

Workflow 2: Fix Stale Cache

# 1. Clean cache for specific package
uv cache clean <package>

# 2. Force refresh
uv pip install --refresh <package>

# 3. If still issues, clean all cache
uv cache clean

# 4. Reinstall
uv pip install --reinstall <package>

Workflow 3: Debug Tool Installation

# 1. Uninstall old version
uv tool uninstall <package>

# 2. Clean build artifacts in source
cd /path/to/source
rm -rf build/ dist/ *.egg-info

# 3. Fresh install
uv tool install --force .

# 4. Verify installation
which <command>
<command> --version

Workflow 4: Test Production Build

# 1. Create clean environment
uv venv test-env
source test-env/bin/activate  # or `test-env\Scripts\activate` on Windows

# 2. Install with no cache
uv pip install --no-cache --reinstall <package>

# 3. Test functionality
python -c "import <package>; print(<package>.__version__)"

# 4. Deactivate and cleanup
deactivate
rm -rf test-env

Official Documentation Links

Cache Concepts: https://docs.astral.sh/uv/concepts/cache/
Build Failures: https://docs.astral.sh/uv/reference/troubleshooting/build-failures/
CLI Reference: https://docs.astral.sh/uv/reference/cli/
Settings: https://docs.astral.sh/uv/reference/settings/

Exit Codes

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

Environment Variables

UV_CACHE_DIR=/path/to/cache           # Cache location
UV_NO_CACHE=1                         # Disable cache
UV_PYTHON=3.13                        # Default Python version
UV_INDEX_URL=https://pypi.org/simple  # Package index
UV_EXTRA_INDEX_URL=https://...        # Additional index
UV_NO_BUILD_ISOLATION=1               # Global build isolation disable
UV_BUILD_CONSTRAINT_DEPENDENCIES      # Build dependency constraints

Configuration File Priority

Command-line flags (highest priority)
Environment variables
pyproject.toml ([tool.uv] section)
uv.toml in project directory
Global config (~/.config/uv/uv.toml)
System defaults (lowest priority)

Common Flag Combinations

Fresh install, no cache:

uv pip install --no-cache --reinstall <package>

Debug with verbose output:

uv pip install --verbose --debug <package>

Force rebuild from source:

uv pip install --no-binary :all: --reinstall <package>

Install with custom constraints:

uv pip install -c constraints.txt --refresh <package>

Tool install with clean build:

cd /path/to/source
rm -rf build/ dist/ *.egg-info
uv tool install --force .

11 KiB Raw Permalink Blame History

UV CLI Reference for Troubleshooting

Overview

Cache Management

uv cache clean

uv cache prune

Cache Refresh Options

--refresh

--refresh-package

--reinstall

Build Isolation Control

--no-build-isolation-package

--no-build-isolation

Installation Options

--force

--editable

--reinstall-package

Build Configuration

--build-constraint

--constraint

Diagnostic Commands

uv pip show

uv pip list

uv pip tree

Environment Management

uv venv

uv sync

Tool Management

uv tool install

uv tool uninstall

uv tool list

Run Commands

uv run

Debug Flags

--verbose

--debug

--no-cache

Cache Location Control

--cache-dir

Common Troubleshooting Workflows

Workflow 1: Resolve Build Failure

Workflow 2: Fix Stale Cache

Workflow 3: Debug Tool Installation

Workflow 4: Test Production Build

Official Documentation Links

Exit Codes

Environment Variables

Configuration File Priority

Common Flag Combinations

11 KiB

Raw Permalink Blame History