skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
laurigates/claude-plugins359 installs

uv-workspaces

Manage multi-package Python projects with uv workspaces. Use when the user mentions uv workspaces, Python monorepo, shared lockfiles, or member dependencies.

How do I install this agent skill?

npx skills add https://github.com/laurigates/claude-plugins --skill uv-workspaces
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    The skill provides comprehensive instructions and tool access for managing Python monorepo projects using uv workspaces. It references official resources from Astral (the creators of uv) and well-known development tools. No security risks were identified.

  • Socketpass

    No alerts

  • Snykpass

    Risk: LOW · No issues

  • Runlayerpass

    2 files scanned · No issues

What does this agent skill do?

UV Workspaces

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

When to Use This Skill

Use this skill when...Use another skill instead when...
Setting up a Python monorepo with shared depsManaging a single package (uv-project-management)
Configuring workspace members and inter-package depsAdding git/URL dependencies (uv-advanced-dependencies)
Using --package or --all-packages flagsBuilding/publishing to PyPI (python-packaging)
Creating virtual workspaces (root with no project)Managing Python versions (uv-python-versions)
Debugging workspace dependency resolutionRunning standalone scripts (uv-run)

Quick Reference

Workspace Structure

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

Root pyproject.toml

[project]
name = "my-workspace"
version = "0.1.0"
requires-python = ">=3.11"

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

# Optional: exclude specific members
exclude = ["packages/experimental"]

Virtual Workspace (No Root Package)

When the root is purely organizational and not a package itself, omit the [project] table:

# Root pyproject.toml — virtual workspace (no [project] table)
[tool.uv.workspace]
members = ["packages/*"]
  • The root is not a workspace member
  • All members live in subdirectories
  • uv run and uv sync require --package or --all-packages (will error without them)

Member pyproject.toml

[project]
name = "my-api"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "my-core",       # Workspace member
    "fastapi",       # External (PyPI)
]

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

Common Commands

OperationCommand
Sync workspace rootuv sync
Sync all membersuv sync --all-packages
Sync specific memberuv sync --package my-api
Run in member contextuv run --package my-api python script.py
Lock entire workspaceuv lock
Upgrade a dependencyuv lock --upgrade-package requests
Build specific packageuv build --package my-core
Add dep to membercd packages/api && uv add requests
Add workspace depcd packages/api && uv add ../core

Key Behaviors

Source Inheritance

Root tool.uv.sources apply to all members unless overridden.

Use case: Define workspace sources in root for all members, override only when a specific member needs a different version:

# Root pyproject.toml — applies to all members
[tool.uv.sources]
my-utils = { workspace = true }

# packages/legacy/pyproject.toml — needs pinned version
[tool.uv.sources]
my-utils = { path = "../utils-v1" }  # Overrides root entirely

Override is per-dependency and total — if a member defines a source for a dependency, the root source for that dependency is ignored completely.

requires-python Resolution

The workspace enforces the intersection of all members' requires-python:

# packages/core: requires-python = ">=3.10"
# packages/api:  requires-python = ">=3.11"
# Effective:     requires-python = ">=3.11"

All members must have compatible Python version requirements.

Editable Installations

Workspace member dependencies are always editable — source changes are immediately available without reinstallation.

Default Scope

CommandDefault scopeOverride
uv lockEntire workspace—
uv syncWorkspace root only--package, --all-packages
uv runWorkspace root only--package, --all-packages
uv buildAll members--package

Workspace vs Path Dependencies

Feature{ workspace = true }{ path = "../pkg" }
Shared lockfileYesNo
Always editableYesOptional
Must be workspace memberYesNo
--package flag worksYesNo
Conflicting deps allowedNoYes

Use path dependencies when members need conflicting requirements or separate virtual environments.

Docker Layer Caching

# Install deps first (cached layer)
COPY pyproject.toml uv.lock packages/*/pyproject.toml ./
RUN uv sync --frozen --no-install-workspace

# Then install project (changes frequently)
COPY . .
RUN uv sync --frozen
FlagEffect
--no-install-projectSkip current project, install deps only
--no-install-workspaceSkip all workspace members, install deps only
--no-install-package <name>Skip specific package(s)
--frozenSkip lockfile freshness check

Agentic Optimizations

ContextCommand
Sync all membersuv sync --all-packages
CI sync (frozen)uv sync --all-packages --frozen
Test specific memberuv run --package my-core pytest --dots --bail=1
Test all membersuv run --all-packages pytest --dots --bail=1
Lock with upgradeuv lock --upgrade-package <dep>
Build one packageuv build --package my-core
Docker deps layeruv sync --frozen --no-install-workspace

See Also

  • uv-project-management — Managing individual packages
  • uv-advanced-dependencies — Path and Git dependencies
  • python-packaging — Building and publishing workspace packages

For detailed workspace patterns (virtual workspaces, Docker integration, source inheritance, syncing strategies), CI/CD examples, and troubleshooting, see REFERENCE.md.

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/laurigates/claude-plugins/uv-workspaces">View uv-workspaces on skillZs</a>