UVによる開発依存関係のインストール

Pythonプロジェクトでパッケージ管理ツールuvを使用する際、開発時に必要な依存関係（テストライブラリやデバッグツールなど）を適切にインストールする方法について解説します。

問題: 開発依存関係のインストール方法が不明

uvでプロジェクト依存関係を管理する際、pyproject.tomlに定義された：

• 本番用依存関係（dependencies）
• 開発用依存関係（dev-dependencies）

の両方を効率的にインストールする方法が明確ではありませんでした。具体的には：

• uv pip compileで生成されるrequirements.txtは本番用のみを含む
• uv syncコマンド実行時にフラットレイアウトエラーが発生するケースがある

error: Multiple top-level packages discovered in a flat-layout:
['conf', 'hines', 'docker', 'assets', 'node_modules']

解決策: dependency-groupsの活用

uvバージョン0.4.0以上では、PEP 735に準拠したdependency-groups機能を使用します。開発依存関係は本番環境に含まれないため[project]セクションではなく、[dependency-groups]セクションで管理します。

Step 1: 正しいpyproject.tomlの構成

[project]
name = "my-project"
dependencies = ["django"]
dynamic = ["version"]
requires-python = ">=3.10"

[dependency-groups]
dev = ["factory-boy"]

重要

• [tool.uv]セクションではなく[dependency-groups]を使用
• devグループ以外にもtest, docsなど任意のグループを定義可能

Step 2: 開発依存関係の追加

パッケージをdevグループに追加する場合:

# ショートカット (devグループ専用)
uv add --dev factory-boy

# 一般形式 (任意のグループ名で使用可能)
uv add --group dev factory-boy

Step 3: 全依存関係のインストール

仮想環境作成と依存関係のインストールを一括実行:

# Pythonバージョン指定 (3.10を使用)
uv venv --python 3.10

# 全依存関係をインストール (デフォルトでdevグループを含む)
uv sync

Step 4: 仮想環境の有効化

source .venv/bin/activate

高度な使用方法

特定グループのみのインストール

# testグループのみインストール
uv sync --group test

# devグループを除外 (本番環境用)
uv sync --no-dev

デフォルトグループの変更

複数のグループをデフォルトインストール対象に設定:

[tool.uv]
default-groups = ["dev", "test"]

Pythonバージョンの固定

プロジェクトのPythonバージョンを明示的に固定:

uv python pin 3.10  # .python-versionファイルを生成

よくあるエラーと解決策

フラットレイアウトエラー

複数トップレベルパッケージ検出時はpyproject.tomlに以下を追加:

[tool.setuptools]
py-modules = []

新旧コマンドの違い

目的	推奨方法	非推奨方法
依存関係インストール	uv sync	uv pip install
開発依存関係追加	uv add --dev	手動編集
ロックファイル生成	uv lock	uv pip compile

ベストプラクティス

1. 依存関係の分類明確化

   • 本番必須 → [project].dependencies
   • 開発専用 → [dependency-groups].dev
   • オプション機能 → [project.optional-dependencies]

2. uvの推奨ワークフロー

3. バージョン固定

   • uv python pinでPythonバージョン固定
   • uv.lockファイルをバージョン管理に含める

注意点

開発依存関係にpytestやmypyなどのツールを含める場合、uv add --devを使用すれば自動的に[dependency-groups]が更新されます。直接pyproject.tomlを編集する必要はありません。

uvの依存関係管理は迅速に進化しています。最新情報については公式ドキュメントを参照してください。