UV Workspacesを使ったPythonモノレポ管理

 (secondb.ai)
18 ポイント 投稿者 darjeeling 2025-11-09 | 1件のコメント | WhatsAppで共有

UV Workspacesを使ったPythonモノレポ管理の要約

この動画では、単一のGitリポジトリで複数のPythonアプリケーション（モノレポ）を管理する際に発生する問題を、UV Workspaces機能を使ってすっきり解決する方法を紹介します。

1. 動画の要約

問題点

1つのリポジトリでCLIツールとFastAPIアプリを同時に開発すると、次のような問題が発生します。

  • コードの重複: CLIとAPIで共通して使う機能（例: ヘッドラインをクロールする関数）をコピー＆ペーストしなければなりません。
  • 複雑な環境管理: 各アプリごとに別々の仮想環境を管理する必要があるため、依存関係のバージョンが衝突したり、ディスク容量が無駄になったりします。

解決策: UV Workspaces

UV Workspacesは、こうした問題を解決するために2つの中核機能を提供します。

  1. 依存関係の共有と単一の仮想環境

    • プロジェクトルート（最上位）にある pyproject.toml ファイルで共通の依存関係を定義できます。
    • uv sync コマンドを実行すると、UVがこの設定ファイルを読み取り、リポジトリ全体で共有する単一の仮想環境（.venv）をルートフォルダに作成します。
    • これにより、すべてのサブプロジェクト（CLI、APIなど）が同じ環境と依存関係を共有するため、バージョン衝突を防ぎ、管理が容易になります。

  2. 内部パッケージによるコード共有

    • 重複する共通コード（例: fetch_headlines 関数）を、core のような別の「内部パッケージ」に分離できます。
    • ワークスペース設定により、この core パッケージをPyPIではなくローカルソースとして認識させます。
    • これでCLIアプリとAPIアプリは、from core.news import fetch_headlines のようにこの共通コードを import して再利用できます。

2. UV Workspacesの使い方

1段階目: ワークスペース設定

プロジェクトのルートフォルダに pyproject.toml ファイルを作成し、[tool.uv.workspace] セクションを定義して、サブプロジェクトがどこにあるかを指定します。

[tool.uv.workspace]  
# "packages" フォルダ内のすべてのサブフォルダをワークスペースメンバーとして認識  
members = ["packages/*"]

2段階目: 依存関係の管理

  • 共有依存関係: すべてのプロジェクトが共通して使う依存関係（例: python-dotenv）は ルートの pyproject.toml に追加します。
  • 個別依存関係: 特定のアプリ（例: api）でのみ使う依存関係（例: fastapi, uvicorn）は そのアプリの pyproject.toml（例: packages/api/pyproject.toml）に追加します。
  • ルートフォルダで uv sync を実行すると、UVがすべての pyproject.toml をスキャンし、ルートの仮想環境に必要な依存関係をすべてインストールします。

3段階目: 内部パッケージとしてコードを共有

  1. packages/core のように、共有コードを格納する新しいパッケージ（フォルダ）を作成します。
  2. ルートの pyproject.toml にこのパッケージを通常の依存関係のように追加します。
  3. ルートの pyproject.toml に [tool.uv.sources] セクションを追加し、core パッケージをPyPIではなくワークスペース内から探すよう設定します。
<!-- end list --> 
[project]  
# 1. 内部パッケージを依存関係として追加  
dependencies = [  
    "core",  
    "python-dotenv"  
]  
  
# 2. 'core' がローカルのワークスペースパッケージであることを明示  
[tool.uv.sources]  
core = { workspace = true }
  1. uv sync を再実行すると、core パッケージがローカルソースとしてインストールされます。
  2. これで packages/api や packages/cli から from core.news import ... 構文で共通コードを読み込めます。

4段階目: プロジェクトの実行

特定のプロジェクトを実行するときは uv run --from <パッケージ名> を使います。

# APIサーバーを実行  
uv run --from packages/api uvicorn main:app --reload  
  
# CLIツールを実行  
uv run --from packages/cli python main.py

3. 利用をおすすめできる対象

  • 1つのリポジトリで複数の小さな自動化スクリプト、Webhook、API、CLIなどを管理するとき。
  • これらのアプリケーションが共通のロジックや依存関係を共有している場合に非常に有用です。
  • 逆に、単一スクリプトやPyPIに独立して配布するパッケージ、あるいは互いにまったく関係のないアプリ群を管理する用途には適さない場合があります。

元動画リンク: https://www.youtube.com/watch?v=N_ypJwV8Q8I

関連記事

1件のコメント

 
pcj9024 2025-11-10

pnpmとかなり似ていますね。