UV Cheatsheet

gistfile1.txt

# UV Package Manager Cheatsheet

## Core Commands

### Installation and Setup
```bash
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Setup Python
uv python install          # Install latest Python
uv python install 3.12     # Install specific Python version
uv python list             # View installed Python versions
```

### Running Scripts
```bash
# Run Python scripts with dependencies
uv run script.py                      # Run a script
uv run --with requests script.py      # Run with a dependency
uv run --with 'requests<3' script.py  # Run with version constraint

# Script with inline metadata
# /// script
# dependencies = ["requests", "rich"]
# requires-python = ">=3.12"
# ///

# Lock script dependencies
uv lock --script script.py            # Create script.py.lock
```

### Managing Tools
```bash
# One-time tool execution
uvx ruff                                # Run tool without installing
uvx ruff@0.3.0                         # Run specific version
uvx --from httpie http                 # Run when package name differs
uvx --with mkdocs-material mkdocs      # Run with plugin

# Install tools
uv tool install ruff                   # Install tool permanently
uv tool install 'ruff>=0.3,<0.4'       # Install with version constraint
uv tool install --python 3.10 ruff     # Install for specific Python

# Upgrade tools
uv tool upgrade ruff                   # Upgrade a tool
uv tool upgrade --all                  # Upgrade all tools
```

### Project Management
```bash
# Create projects
uv init myproject                # Create new project
uv init --app                    # Create application project
uv init --lib mylib              # Create library project
uv init --script script.py       # Create script with metadata

# Manage dependencies
uv add requests                  # Add dependency
uv add 'requests==2.31.0'        # Add with version constraint
uv add -r requirements.txt       # Add from requirements file
uv add --dev pytest              # Add development dependency
uv add --script script.py rich   # Add dependency to script

uv remove requests               # Remove dependency

# Run in project
uv run main.py                   # Run script in project
uv run pytest                    # Run command in project
uv run --no-project script.py    # Run without project dependencies

# Sync and lock
uv sync                          # Install dependencies
uv sync --frozen                 # Install using lockfile
uv lock                          # Update lockfile
uv lock --upgrade-package requests  # Upgrade specific package
```

### Building and Publishing
```bash
# Build package
uv build                         # Build package
uv build --no-sources            # Build without custom sources

# Publish package
uv publish                       # Publish to PyPI
uv publish --index testpypi      # Publish to custom index
```

## Alternative Package Indexes

```toml
# In pyproject.toml
[[tool.uv.index]]
name = "private-registry"
url = "https://private-registry.com/simple/"
publish-url = "https://private-registry.com/legacy/"
explicit = true  # Only use for specified packages
```

```bash
# Set credentials for private registry
export UV_INDEX_PRIVATE_REGISTRY_USERNAME=username
export UV_INDEX_PRIVATE_REGISTRY_PASSWORD=password

# Publish to private registry
uv publish --index private-registry
```

## Docker Integration

```dockerfile
# Use uv in Docker
FROM python:3.12-slim

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

# Cache dependencies with multi-stage build
WORKDIR /app
RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --frozen --no-install-project

# Copy project and sync
COPY . /app
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen

# Set environment variables
ENV UV_COMPILE_BYTECODE=1   # Compile bytecode
ENV UV_LINK_MODE=copy       # Use copy instead of links
```

## CI/CD Integration

```yaml
# GitHub Actions
- name: Install uv
  uses: astral-sh/setup-uv@v5
  with:
    version: "0.6.7"      # Pin specific version
    enable-cache: true    # Cache dependencies

# GitLab CI
variables:
  UV_VERSION: 0.6.7
  UV_CACHE_DIR: .uv-cache
  UV_LINK_MODE: copy

cache:
  - key:
      files:
        - uv.lock
    paths:
      - $UV_CACHE_DIR
```

Remember that uv automatically manages virtual environments and Python versions, making it easier to work with Python projects consistently across different environments.