uv-workspaces

# UV Workspaces

Quick reference for managing monorepo and multi-package projects with UV workspaces.

## When This Skill Applies

- Monorepo projects with multiple Python packages
- Shared dependencies across multiple packages
- Library packages with example applications
- Projects with plugins or extensions
- Internal package dependencies

## Quick Reference

### Workspace Structure

```
my-workspace/
├── pyproject.toml          # Root workspace config
├── uv.lock                # Shared lockfile
├── packages/
│   ├── core/
│   │   ├── pyproject.toml
│   │   └── src/core/
│   ├── api/
│   │   ├── pyproject.toml
│   │   └── src/api/
│   └── cli/
│       ├── pyproject.toml
│       └── src/cli/
└── README.md
```

### Root pyproject.toml

```toml
[tool.uv.workspace]
members = [
    "packages/*",
]

# Or explicit:
members = [
    "packages/core",
    "packages/api",
    "packages/cli",
]

# Exclude patterns
exclude = [
    "packages/experimental",
]
```

### Package pyproject.toml

```toml
[project]
name = "my-core"
version = "0.1.0"
dependencies = []

# Depend on workspace member
[project]
dependencies = ["my-utils"]

[tool.uv.sources]
my-utils = { workspace = true }
```

## Common Commands

```bash
# Install all workspace members
uv sync

# Build specific package
uv build --package my-core

# Run in package context
uv run --package my-api python script.py

# Add dependency to specific member
cd packages/my-core
uv add requests

# Lock entire workspace
uv lock
```

## Workspace Members

### Declaring Members

```toml
[tool.uv.workspace]
# Glob patterns
members = ["packages/*"]

# Explicit paths
members = [
    "packages/core",
    "apps/web",
    "tools/cli",
]

# Mixed
members = [
    "packages/*",
    "apps/special",
]

# Exclusions
exclude = ["packages/archived"]
```

### Member Dependencies

**Depend on another workspace member:**
```toml
# packages/api/pyproject.toml
[project]
name = "my-api"
dependencies = [
    "my-core",  # Workspace member
    "fastapi",  # P