uvの依存グループを--devと--group devで使い分ける

公開日:

2026-05-24

uvでdev依存性を追加するときに uv add --dev pytest と書く流派もあれば、uv add --group dev pytest と書く流派もあって、どっちが正しいか迷うことありますよね。結論から言うと両者は等価で、--dev は --group dev の省略形です。

--dev と --group dev は等価

uvは PEP 735 の [dependency-groups] 表で開発依存を管理する。dev グループは特別扱いされていて、--dev --only-dev --no-dev の省略形フラグが用意されている。

公式ドキュメントは --dev --only-dev --no-dev をそれぞれ --group dev --only-group dev --no-group dev と等価と明記している^[1]。pyproject.toml への書き出しも同じで、どちらも [dependency-groups] の dev に追加される。

uv add --dev pytest
uv add --group dev pytest

どちらを実行しても pyproject.toml には同じ結果が書かれる。

[dependency-groups]
dev = [
    "pytest>=8.0.0",
]

加えて dev グループは「デフォルトで sync される」点も特別扱いされている。uv sync を引数なしで実行すると dev グループの依存性も一緒に同期される。

用途別に依存グループを分けて整理する

--group フラグの本当の価値は dev 以外のグループを作れることにある。lint や test、docs のように用途別にグループを分けると、CI で必要なものだけを入れて sync を軽くできる。

uv add --group lint ruff
uv add --group test pytest pytest-cov
uv add --group docs mkdocs mkdocs-material

pyproject.toml は次のようになる。

[dependency-groups]
dev = [
    "ipython>=8.0.0",
]
lint = [
    "ruff>=0.5.0",
]
test = [
    "pytest>=8.0.0",
    "pytest-cov>=5.0.0",
]
docs = [
    "mkdocs>=1.6.0",
    "mkdocs-material>=9.5.0",
]

最初は --dev だけで全部 dev に入れていたけれど、GitHub Actions で lint ジョブと test ジョブを分けたら docs の依存性まで毎回入って sync 時間が無駄に伸びた。lint/test/docs に分けて、各ジョブで --only-group を指定したら sync が早くなった。