UV Troubleshooting Guide

Solutions to common issues when using UV with this project.

Installation Issues

UV Command Not Found

Problem: After installing UV, command not found error.

Solution:

# Add UV to PATH
export PATH="$HOME/.local/bin:$PATH"

# Make it permanent
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Verify
uv --version

Alternative: Install via pip/pipx which handles PATH automatically:

pipx install uv
# or
pip install uv

Installation Fails on macOS

Problem: Permission denied or certificate errors.

Solution:

# Use curl with different options
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or install via Homebrew
brew install uv

Installation Fails on Windows

Problem: PowerShell execution policy prevents installation.

Solution:

# Run PowerShell as Administrator
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Then install
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Sync Issues

Sync Fails with “Failed to build” Error

Problem: uv sync fails when building a package.

Solution 1 - Clear cache and retry:

uv cache clean
uv sync

Solution 2 - Check Python version:

# Ensure Python 3.13 is available
uv python list
uv python install 3.13

# Verify .python-version is correct
cat .python-version
# Should show: 3.13

Solution 3 - Check package configuration:

# Ensure pyproject.toml has correct build backend
# Should have:
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Lock File Out of Date

Problem: Error message about lock file being out of date.

Solution:

# Regenerate lock file
uv lock

# Then sync
uv sync

Dependency Conflict

Problem: uv sync reports dependency conflicts.

Solution 1 - See detailed conflict information:

uv sync --verbose

Solution 2 - Try upgrading dependencies:

uv lock --upgrade
uv sync

Solution 3 - If a specific package is conflicting:

# Update the problematic package
uv add "package-name>=version"

# Or remove and re-add
uv remove package-name
uv add package-name

Python Version Issues

Python 3.13 Not Found

Problem: UV can’t find Python 3.13.

Solution:

# Install Python 3.13 via UV
uv python install 3.13

# Verify installation
uv python list --only-installed

# Pin the version
uv python pin 3.13

Wrong Python Version Being Used

Problem: UV is using wrong Python version.

Solution:

# Check what's being used
uv run python --version

# Pin to correct version
uv python pin 3.13

# Remove old .venv and resync
rm -rf .venv
uv sync

Multiple Python Versions Conflict

Problem: System has multiple Python versions causing issues.

Solution:

# Use UV's Python explicitly
uv python install 3.13.7
uv python pin 3.13.7

# Set environment variable
export UV_PYTHON=3.13

# Or specify in command
uv sync --python 3.13

Package Issues

Package Not Found After Installation

Problem: Module import fails even after successful install.

Solution 1 - Use uv run:

# Instead of:
python -c "import package_name"

# Use:
uv run python -c "import package_name"

Solution 2 - Ensure package is in workspace:

# Check root pyproject.toml has the package
cat pyproject.toml | grep -A 10 "workspace"

# If missing, add it and resync
uv sync

Solution 3 - Rebuild the package:

cd src/package-name
uv pip install -e .

Package Import Error in IDE

Problem: IDE shows import errors even though package is installed.

Solution:

VS Code:

Open Command Palette (Cmd/Ctrl + Shift + P)
Select “Python: Select Interpreter”
Choose .venv/bin/python
Reload window

PyCharm:

Settings → Project → Python Interpreter
Add Interpreter → Existing Environment
Select .venv/bin/python
Apply changes

Editable Install Not Working

Problem: Changes to package code not reflected.

Solution:

# Reinstall in editable mode
cd src/package-name
uv pip install -e . --force-reinstall

# Or rebuild everything
cd ../..
make clean
make build

Performance Issues

Slow Sync on First Run

Problem: First uv sync takes a long time.

Explanation: This is normal! UV is:

Downloading packages (only once)
Building wheels (cached for future use)
Installing everything

Solution: Subsequent syncs will be 10-100x faster due to caching.

Hardlink Warnings

Problem: Warning about falling back to full copy.

warning: Failed to hardlink files; falling back to full copy.

Solution:

# Use copy mode explicitly
export UV_LINK_MODE=copy

# Make permanent
echo 'export UV_LINK_MODE=copy' >> ~/.bashrc

# Or set in command
uv sync --link-mode=copy

Explanation: This happens when .venv and cache are on different filesystems. Copy mode is slower but works everywhere.

Large Disk Space Usage

Problem: UV cache taking up lots of space.

Solution:

# Check cache size
du -sh ~/.cache/uv

# Clean cache (keeps only recent packages)
uv cache clean

# Remove entire cache (will re-download on next sync)
rm -rf ~/.cache/uv

Environment Issues

Virtual Environment Broken

Problem: .venv is corrupted or broken.

Solution:

# Delete and recreate
rm -rf .venv
uv sync

# If that fails, also clear cache
uv cache clean
rm -rf .venv
uv sync

Environment Variables Not Working

Problem: Environment variables not being recognized.

Solution:

# Check if variables are set
printenv | grep UV

# Set temporarily
export UV_LINK_MODE=copy

# Set permanently in shell config
echo 'export UV_LINK_MODE=copy' >> ~/.bashrc
source ~/.bashrc

Permissions Errors

Problem: Permission denied errors.

Solution:

# Check ownership
ls -la .venv

# Fix ownership
sudo chown -R $USER:$USER .venv

# Recreate if needed
rm -rf .venv
uv sync

Build Issues

Build Fails with “Hatchling” Error

Problem: Build fails with hatchling-related errors.

Solution:

# Ensure pyproject.toml has correct config
cat src/package-name/pyproject.toml

# Should have:
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

# And NOT:
[tool.setuptools]  # Remove this if present

Make Build Fails

Problem: make build fails.

Solution 1 - Check UV is accessible:

which uv
# Should show: /home/user/.local/bin/uv

# If not, add to PATH
export PATH="$HOME/.local/bin:$PATH"

Solution 2 - Clean and rebuild:

make clean
uv sync
make build

Solution 3 - Run build script directly:

./build.sh

Tests Fail to Import Packages

Problem: Tests can’t import project packages.

Solution:

# Ensure packages are installed in dev mode
make build

# Run tests with uv run
uv run pytest

# Or
make test

Workspace Issues

Workspace Member Not Recognized

Problem: Package not being picked up as workspace member.

Solution:

# Check root pyproject.toml
cat pyproject.toml | grep -A 20 "workspace"

# Ensure package is listed
[tool.uv.workspace]
members = [
    "src/your-package",  # Add if missing
]

# Resync
uv sync

Workspace Conflict

Problem: Multiple packages define same dependency with different versions.

Solution:

# See conflict details
uv sync --verbose

# Option 1: Align versions in all packages
# Edit pyproject.toml in each package to use same version

# Option 2: Use version range
# Instead of "package==1.0.0"
# Use "package>=1.0.0,<2.0.0"

# Option 3: Override in root
[tool.uv.override-dependencies]
problematic-package = "1.0.0"

CI/CD Issues

CI Build Fails with UV

Problem: CI/CD pipeline fails when using UV.

Solution:

# Install UV in CI
- name: Install UV
  run: curl -LsSf https://astral.sh/uv/install.sh | sh

# Add to PATH
- name: Add UV to PATH
  run: echo "$HOME/.local/bin" >> $GITHUB_PATH

# Use frozen sync for reproducibility
- name: Install dependencies
  run: uv sync --frozen

# Run tests
- name: Run tests
  run: uv run pytest

Docker Build Fails

Problem: Docker build can’t find UV.

Solution:

FROM python:3.13-slim

# Install UV
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

# Copy project files
WORKDIR /app
COPY pyproject.toml uv.lock ./
COPY src/ ./src/

# Install dependencies
RUN uv sync --frozen --no-dev

CMD ["uv", "run", "python", "main.py"]

Network Issues

Download Failures

Problem: Package downloads fail.

Solution:

# Retry with verbose output
uv sync --verbose

# Use specific index
uv sync --index-url https://pypi.org/simple

# Work offline (use cached packages only)
export UV_OFFLINE=1
uv sync

Proxy Issues

Problem: UV can’t download packages behind proxy.

Solution:

# Set proxy environment variables
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

# Then sync
uv sync

# Or use pip-compatible config
export PIP_PROXY=http://proxy.company.com:8080
uv sync

Getting More Help

Enable Verbose Output

# See detailed information
uv sync --verbose

# See even more details
uv -vv sync

Check UV Version

# Check version
uv --version

# Update UV
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or via pip
pip install --upgrade uv

Report a Bug

If you encounter a UV bug:

Check existing issues: https://github.com/astral-sh/uv/issues

Collect information:

uv --version
uv python list
cat .python-version
cat pyproject.toml

Create minimal reproduction
Report: https://github.com/astral-sh/uv/issues/new

Project-Specific Help

For issues specific to this project:

Check documentation:
Ask the team: Open an issue in the project repository
Check Makefile: make help

Quick Diagnostic Checklist

Run these commands to diagnose most issues:

# 1. Check UV installation
uv --version

# 2. Check Python version
uv python list --only-installed

# 3. Check .python-version
cat .python-version

# 4. Check root pyproject.toml
cat pyproject.toml | head -30

# 5. Check for .venv
ls -la .venv

# 6. Try clean sync
rm -rf .venv
uv cache clean
uv sync --verbose

# 7. Try build
make build

# 8. Try test
make test

If all else fails:

# Nuclear option - full reset
make clean
rm -rf .venv
uv cache clean
uv sync
make build
make test