uvでdevグループを除外してもパッケージが残る理由：default-groupsの確認方法

uv sync --no-devが外すのはdevグループだけです。tool.uv.default-groupsにlintなど別の既定グループが含まれていれば、それらは同期対象に残り得ます。既定グループをすべて外したい場合は、--no-default-groupsを使います。

ここでは、設定の確認、3つの同期方法の使い分け、実際の仮想環境の検査、起動時の条件合わせまでを順に整理します。最終的に、lockファイルに名前があるだけなのか、現在の.venvへ本当に導入されているのかを切り分けられます。

まずpyproject.tomlの3か所を確認する

読者自身のpyproject.tomlで、通常依存のproject.dependencies、各グループを定義するdependency-groups、既定で選ばれるtool.uv.default-groupsを確認します。次は違いを見やすくするための架空の最小例です。詳しい考え方はuvの依存関係グループの公式説明でも確認できます。

[project]
name = "sample-app"
version = "0.1.0"
dependencies = [
  "requests",
]

[dependency-groups]
dev = [
  "pytest",
]
lint = [
  "ruff",
]

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

この設定では、通常依存はrequests、開発グループはpytest、静的検査グループはruffです。既定グループにdevとlintの両方が指定されている点が重要です。

3つの同期方法を使い分ける

devだけを外す

--no-devは--no-group devと同じ意味です。上の例ではdevだけが除外され、既定グループのlintは残ります。

uv sync --no-dev

既定グループをすべて外す

通常依存だけを基準にしたいときは、すべての既定グループを無効化します。同期オプションの詳細はuvのプロジェクト同期の公式説明を参照してください。

uv sync --no-default-groups

必要な1グループだけ戻す

既定グループをいったん無効化し、必要なグループだけを明示的に追加できます。次の例は通常依存に加えてlintだけを選びます。

uv sync --no-default-groups --group lint

除外指定と包含指定が重なった場合は、除外指定が優先されます。意図した結果にならないときは、追加したグループだけでなく、同時に指定した除外オプションも確認してください。

残ったパッケージは依存元を確認する

--no-devを付けても、同じパッケージがproject.dependenciesにある、別の選択中グループにも含まれる、または必要なパッケージの推移依存になっている場合は、環境に必要なままです。パッケージ名だけを見て「dev由来だから消えるはず」と判断せず、通常依存、選択中グループ、推移依存のどこから要求されているかを確認します。

uv.lockではなく実際の.venvを検査する

依存グループはlock作成時にまとめて解決されるため、uv.lockにパッケージ名があることは、現在の仮想環境へ導入済みである証拠ではありません。検査では対象のPythonを直接指定します。Windowsでは次のパスを使います。

uv pip list --python .venv/Scripts/python.exe

macOSやLinuxなどのUnix系環境では、仮想環境内のPythonの場所が異なります。

uv pip list --python .venv/bin/python

検査のために無指定のuv runを実行すると、環境が既定グループの選択へ同期し直される可能性があります。確認だけなら上のように対象Pythonを直接指定するか、すでに同期済みの環境を--no-syncで使います。

普段の起動条件も同期条件に合わせる

通常の起動でも、同期時と同じグループ選択をuv runへ渡すか、必要な依存を先に同期したうえで同期を行わずに起動します。次のapp.pyは説明用のファイル名です。

uv run --no-sync python app.py

--no-syncは依存関係を準備する機能ではありません。必要な同期が済んでいる環境を、その状態のまま使うための指定です。

FAQ

Q. uv.lockからdev関連の記録を消す必要がありますか？

通常はその必要はありません。lockは選択可能なグループを含めて解決結果を記録し、.venvは今回の同期条件に応じた導入状態を持ちます。確認すべきなのはlock内の名前の有無ではなく、実環境と依存元です。

Q. --only-groupならアプリ実行用の最小環境になりますか？

--only-groupは指定グループだけを対象にし、プロジェクト自体とその依存関係を省きます。そのため、通常のアプリを動かす環境から不要な開発依存だけを外す指定とは意味が異なります。

実行するPython自体が想定と違う場合は、uv python pin後のPATHとuv runの切り分けも確認してください。