uv-workspaces

UV ワークスペース

UV ワークスペースを使ってモノレポやマルチパッケージプロジェクトを管理するためのクイックリファレンスです。

このスキルを使う場面

次の場合はこのスキルを使います…	次の場合は別のスキルを使います…
共有依存関係を持つ Python モノレポをセットアップするとき	単一パッケージを管理するとき（uv-project-management）
ワークスペースのメンバーやパッケージ間の依存関係を設定するとき	Git／URL 依存関係を追加するとき（uv-advanced-dependencies）
--package または --all-packages フラグを使うとき	PyPI 向けにビルド／公開するとき（python-packaging）
仮想ワークスペースを作成するとき（プロジェクトを含まないルート）	Python のバージョンを管理するとき（uv-python-versions）
ワークスペースの依存関係解決をデバッグするとき	スタンドアロンのスクリプトを実行するとき（uv-run）

クイックリファレンス

ワークスペースの構成

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

ルートの 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"]

仮想ワークスペース（ルートパッケージなし）

ルートが純粋に整理目的であり、パッケージ自体ではない場合は、[project] テーブルを省略します。

# Root pyproject.toml — virtual workspace (no [project] table)
[tool.uv.workspace]
members = ["packages/*"]

• ルートはワークスペースのメンバーではありません
• すべてのメンバーはサブディレクトリに配置します
• uv run と uv sync には --package または --all-packages が必要です（指定しないとエラーになります）

メンバーの 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 }

よく使うコマンド

操作	コマンド
ワークスペースのルートを同期する	uv sync
すべてのメンバーを同期する	uv sync --all-packages
特定のメンバーを同期する	uv sync --package my-api
メンバーのコンテキストで実行する	uv run --package my-api python script.py
ワークスペース全体をロックする	uv lock
依存関係をアップグレードする	uv lock --upgrade-package requests
特定のパッケージをビルドする	uv build --package my-core
メンバーに依存関係を追加する	cd packages/api && uv add requests
ワークスペース依存関係を追加する	cd packages/api && uv add ../core

主な動作

ソースの継承

ルートの tool.uv.sources は、上書きされない限りすべてのメンバーに適用されます。

ユースケース：すべてのメンバー向けにワークスペースのソースをルートで定義し、特定のメンバーで異なるバージョンが必要な場合にのみ上書きします。

# 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

上書きは依存関係ごとに行われ、完全に置き換わります。メンバーがある依存関係のソースを定義すると、その依存関係に対するルートのソースは完全に無視されます。

requires-python の解決

ワークスペースでは、すべてのメンバーの requires-python の共通部分が適用されます。

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

すべてのメンバーで、互換性のある Python バージョン要件を指定する必要があります。

編集可能なインストール

ワークスペースメンバーの依存関係は常に編集可能です。ソースを変更すると、再インストールせずにすぐ反映されます。

デフォルトの適用範囲

コマンド	デフォルトの適用範囲	上書き
uv lock	ワークスペース全体	—
uv sync	ワークスペースのルートのみ	--package, --all-packages
uv run	ワークスペースのルートのみ	--package, --all-packages
uv build	すべてのメンバー	--package

ワークスペースとパス依存関係の比較

機能	{ workspace = true }	{ path = "../pkg" }
共有ロックファイル	はい	いいえ
常に編集可能	はい	任意
ワークスペースのメンバーである必要がある	はい	いいえ
--package フラグが使える	はい	いいえ
競合する依存関係を許可	いいえ	はい

メンバー間で要件が競合する場合や、個別の仮想環境が必要な場合は、パス依存関係を使います。

Docker のレイヤーキャッシュ

# 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

フラグ	効果
--no-install-project	現在のプロジェクトをスキップし、依存関係のみをインストールします
--no-install-workspace	すべてのワークスペースメンバーをスキップし、依存関係のみをインストールします
--no-install-package <name>	特定のパッケージをスキップします
--frozen	ロックファイルの最新状態チェックをスキップします

エージェント向けの最適化

コンテキスト	コマンド
すべてのメンバーを同期	uv sync --all-packages
CI 同期（固定）	uv sync --all-packages --frozen
特定のメンバーをテスト	uv run --package my-core pytest --dots --bail=1
すべてのメンバーをテスト	uv run --all-packages pytest --dots --bail=1
アップグレードしてロック	uv lock --upgrade-package <dep>
1 つのパッケージをビルド	uv build --package my-core
Docker の依存関係レイヤー	uv sync --frozen --no-install-workspace

関連項目

• uv-project-management — 個別のパッケージの管理
• uv-advanced-dependencies — パス依存関係と Git 依存関係
• python-packaging — ワークスペースパッケージのビルドと公開

詳細なワークスペースのパターン（仮想ワークスペース、Docker との統合、ソースの継承、同期戦略）、CI/CD の例、トラブルシューティングについては、REFERENCE.md を参照してください。