公式
Handling of extraneous packages
uvのバージョン
uv self version
>>uv 0.11.3 (45da18ac3 2026-04-01 aarch64-apple-darwin)
概要
uv syncやuv runを実行するとuvが自動でuv.lockと仮想環境を同期してくれます。
しかし、同期の挙動に若干違いがあり、前者は厳密な同期を、後者は厳密でない同期を行います。
もう少しわかりやすく言うと、uv syncの同期は、仮想環境に必要最低限の依存関係のみインストールされた_状態にしますが、uv runの同期は、必要最低限の依存関係のみの状態にならない可能性があります。
必要最低限の依存関係
uvでは{dependencies} + {default-groupsに含まれるdependency-groups} = {必要最低限の依存関係}です。
何も指定しない場合、default groupsにはdevグループが含まれます。
default groupsについては後述します。
exact syncing
必要最低限の依存関係のみの状態にする同期は、ドキュメント内でexact syncingと表現されています。
冒頭「厳密な同期」と言ったのはこれの直訳です。
uv syncのデフォルトはexact syncingです。
uv syncでも、uv runでも、--exactオプションをつけることで、exact syncingになります。
[project]
name = "uv-sync-example"
version = "0.1.0"
description = "Uv sync example project."
readme = "README.md"
requires-python = ">=3.14"
dependencies = [
"requests>=2.33.1",
]
[dependency-groups]
build = [
"pyinstaller>=6.19.0",
]
dev = [
"ruff>=0.15.9",
"ty>=0.0.28",
]
全てのグループの依存関係を入れた後に、uv syncすると余分なライブラリが消えます。
uv sync --all-groups
>>Using CPython 3.14.2
>>Creating virtual environment at: .venv
>>Resolved 16 packages in 0.78ms
>>Installed 13 packages in 25ms
>> + altgraph==0.17.5
>> + certifi==2026.2.25
>> + charset-normalizer==3.4.7
>> + idna==3.11
>> + macholib==1.16.4
>> + packaging==26.0
>> + pyinstaller==6.19.0
>> + pyinstaller-hooks-contrib==2026.4
>> + requests==2.33.1
>> + ruff==0.15.9
>> + setuptools==82.0.1
>> + ty==0.0.28
>> + urllib3==2.6.3
uv sync
>>Resolved 16 packages in 25ms
>>Uninstalled 6 packages in 117ms
>> - altgraph==0.17.5
>> - macholib==1.16.4
>> - packaging==26.0
>> - pyinstaller==6.19.0
>> - pyinstaller-hooks-contrib==2026.4
>> - setuptools==82.0.1
uv runを--exactで実行しても同じ結果になります。
同期の挙動を表示するために--verboseオプションを付けてます。
uv sync --all-groups
uv run --exact --verbose main.py
>>...
>>Uninstalled 6 packages in 99ms
>> - altgraph==0.17.5
>> - macholib==1.16.4
>> - packaging==26.0
>> - pyinstaller==6.19.0
>> - pyinstaller-hooks-contrib==2026.4
>> - setuptools==82.0.1
>>...
inexact syncing
対して、余分な依存関係を許容する同期はinexact syncingと表現されています。
直訳すると「厳密でない同期」です。
uv runのデフォルトがinexact syncingです。
uv syncでも--inexactオプションでinexact syncingになります。
exactの場合と同様に確認します。
inexact syncingの場合、余分なライブラリがあっても削除されません。
uv sync --all-groups
uv run --verbose main.py
>>...
>>Resolved 16 packages in 24ms
>>...
uv sync --inexactでも同じ挙動です。
uv sync --all-groups
uv sync --inexact
>>Resolved 16 packages in 4ms
>>Checked 7 packages in 1ms
default groups
default groupsはpyproject.tomlの中で、以下のように設定できます。
[tool.uv]
default-groups = ["dev", "build"]
default groupsを変更してuv syncすると追加したbuildグループも含めて同期します。
rm -rf .venv
uv sync
>>Using CPython 3.14.2
>>Creating virtual environment at: .venv
>>Resolved 16 packages in 8ms
>>Installed 13 packages in 23ms
>> + altgraph==0.17.5
>> + certifi==2026.2.25
>> + charset-normalizer==3.4.7
>> + idna==3.11
>> + macholib==1.16.4
>> + packaging==26.0
>> + pyinstaller==6.19.0
>> + pyinstaller-hooks-contrib==2026.4
>> + requests==2.33.1
>> + ruff==0.15.9
>> + setuptools==82.0.1
>> + ty==0.0.28
>> + urllib3==2.6.3
また、--no-default-groupsオプションを使用することでuv syncやuv run実行時にdefault groupsを外すこともできます。
uv runのデフォルトはinexact syncingなので--exactも必要ですね。
uv run --no-default-groups --exact --verbose main.py
>>...
>>Uninstalled 8 packages in 130ms
>> - altgraph==0.17.5
>> - macholib==1.16.4
>> - packaging==26.0
>> - pyinstaller==6.19.0
>> - pyinstaller-hooks-contrib==2026.4
>> - ruff==0.15.9
>> - setuptools==82.0.1
>> - ty==0.0.28
>>...
その他のオプション
その他のグループ周りのオプションをいくつか示します。
ただ、示すオプションはほんの一部なのでuv sync -h uv run -hの結果や公式ドキュメントを定期的に眺めてみることをおすすめします。
ちなみに記事執筆時点の最新バージョンは0.11.3です。
--group/--no-group
特定のグループの依存関係を含めたい/含めたくない場合に使えます。
uv sync --group build --no-group dev
>>Using CPython 3.14.2
>>Creating virtual environment at: .venv
>>Resolved 16 packages in 7ms
>>Installed 11 packages in 32ms
>> + altgraph==0.17.5
>> + certifi==2026.2.25
>> + charset-normalizer==3.4.7
>> + idna==3.11
>> + macholib==1.16.4
>> + packaging==26.0
>> + pyinstaller==6.19.0
>> + pyinstaller-hooks-contrib==2026.4
>> + requests==2.33.1
>> + setuptools==82.0.1
>> + urllib3==2.6.3
--only-dev/--no-dev
devグループの依存関係のみを含めたい/含めたくない場合に使えます。
--only-devはdependenciesの依存関係も入りません。
--no-devは--no-group devと同じですね。
uv sync --only-dev
>>Using CPython 3.14.2
>>Creating virtual environment at: .venv
>>Resolved 16 packages in 0.77ms
>>Installed 2 packages in 2ms
>> + ruff==0.15.9
>> + ty==0.0.28
uv sync --no-dev
>>Resolved 16 packages in 16ms
>>Uninstalled 2 packages in 2ms
>>Installed 11 packages in 33ms
>> + altgraph==0.17.5
>> + certifi==2026.2.25
>> + charset-normalizer==3.4.7
>> + idna==3.11
>> + macholib==1.16.4
>> + packaging==26.0
>> + pyinstaller==6.19.0
>> + pyinstaller-hooks-contrib==2026.4
>> + requests==2.33.1
>> - ruff==0.15.9
>> + setuptools==82.0.1
>> - ty==0.0.28
>> + urllib3==2.6.3
--only-group
特定のグループの依存関係のみを含めたい場合に使えます。
これもdependenciesの依存関係が入りません。
uv sync --only-group build
>>Using CPython 3.14.2
>>Creating virtual environment at: .venv
>>Resolved 16 packages in 7ms
>>Installed 6 packages in 25ms
>> + altgraph==0.17.5
>> + macholib==1.16.4
>> + packaging==26.0
>> + pyinstaller==6.19.0
>> + pyinstaller-hooks-contrib==2026.4
>> + setuptools==82.0.1
--all-groups
全てのグループの依存関係を含めたい場合に使えます。
上でさんざん使ったので例は省略します。
おわりに
exactはたぶん「ぴったり」「まさに」「ちょうど」みたいなニュアンスの単語だと思います。
知らんけど。