Workspaces#
ワークスペースは、独立した依存関係を持つ複数のパッケージに分割することで、大規模なコードベースを編成するのに役立ちます。ワークスペース内の各パッケージには独自のpyproject.tomlがありますが、それらはすべて共有ロックファイルにロックされ、共有仮想環境にインストールされます。
Using the project interface, uv run and uv sync will install all packages of the workspace, unless you select a single workspace member with --package. When using the uv pip interface, workspace dependencies behave like editable path dependencies.
When (not) to use workspaces#
ワークスペースの一般的なユースケースの1つは、コードベースが大きくなり、最終的にはいくつかのモジュールを独自の依存関係仕様を持つ独立したパッケージにすることである。他のユースケースは、異なる責任を持つコードベースの部分を分離することである。例えば、ライブラリパッケージとCLIパッケージを持つリポジトリでは、CLIパッケージはライブラリの機能を利用可能にするが、追加の依存関係がある、バックエンドとインジェストパッケージを持つWebサーバ、またはパフォーマンスが重要なサブルーチンをネイティブ言語で実装したライブラリなどである。
ワークスペースは、すべてのメンバーをまとめてインストールしない場合、メンバーの要件が競合している場合、または単にプロジェクトごとに個別の仮想環境が必要な場合には適していません。この場合は、通常の(編集可能な)相対パスの依存関係を使用します。
現在、ワークスペースは異なるrequires-python値を持つ異なるメンバーを適切にサポートしていません。すべてのrequires-python下限のうち最も高いものをワークスペース全体に適用します。古い仮想環境に個々のメンバーをインストールするには、uv pipを使用する必要があります。
Note
Pythonは依存関係の分離を提供しないので、uvは、パッケージが宣言した依存関係のみを使用し、別の依存関係のためにインストールされたパッケージをインポートしないことを保証できません。特にワークスペースの場合、uvは、パッケージが別のワークスペースメンバーによって宣言された依存関係をインポートしないことを保証できません。
Usage#
ワークスペースは、ワークスペースルートになるpyproject.tomlにtool.uv.workspaceテーブルを追加することで作成できます。このテーブルにはmembers(必須)とexclude(オプション)が含まれ、ディレクトリのglobのリストも含まれています。
[tool.uv.workspace]
members = ["packages/*", "examples/*"]
exclude = ["example/excluded_example"]
ワークスペース全体のuv.lockと.venvは、このpyproject.tomlの隣に作成されます。すべてのメンバーはその下のディレクトリに存在する必要があります。
ワークスペースルートでtool.uv.sourcesが定義されている場合は、特定のメンバーのtool.uv.sourcesでオーバーライドされない限り、すべてのメンバーに適用されます。
ワークスペース内でuv initを使用すると、新しく作成されたパッケージがmembersに追加されます。
Common structures#
2つの主要なワークスペース構造があります:ヘルパー付きのルートパッケージとフラットワークスペースです。
ルートワークスペースレイアウトは、リポジトリのルートに1つのメインパッケージを定義し、packagesにヘルパーパッケージを定義します。この例では、albatross/pyproject.tomlにprojectセクションとtool.uv.workspaceセクションの両方があります。
albatross
├── packages
│ ├── provider_a
│ │ ├── pyproject.toml
│ │ └── src
│ │ └── provider_a
│ │ ├── __init__.py
│ │ └── foo.py
│ └── provider_b
│ ├── pyproject.toml
│ └── src
│ └── provider_b
│ ├── __init__.py
│ └── bar.py
├── pyproject.toml
├── README.md
├── uv.lock
└── src
└── albatross
└── main.py
フラットレイアウトでは、すべてのパッケージはpackagesディレクトリにあり、ルートpyproject.tomlはいわゆる仮想ワークスペースを定義します。この例では、albatross/pyproject.tomlにはtool.uv.workspaceセクションしかありませんが、projectはありません。
albatross
├── packages
│ ├── albatross
│ │ ├── pyproject.toml
│ │ └── src
│ │ └── albatross
│ │ ├── __init__.py
│ │ └── foo.py
│ ├── provider_a
│ │ ├── pyproject.toml
│ │ └── src
│ │ └── provider_a
│ │ ├── __init__.py
│ │ └── foo.py
│ └── provider_b
│ ├── pyproject.toml
│ └── src
│ └── provider_b
│ ├── __init__.py
│ └── bar.py
├── pyproject.toml
├── README.md
└── uv.lock
フラットレイアウトでは、ワークスペースルートpyproject.tomlで開発依存関係を定義できます。