uv を使ってプロジェクトを管理し始めると、次に気になるのがライブラリの更新です。
たとえば、こんなときです。
- セキュリティ修正が入った
- バグ修正を取り込みたい
- 新しい機能を使いたい
ただし、uv は勝手に最新へ上げ続けるわけではありません。
ここが、再現性のために大事なポイントです。
先に結論
ライブラリ更新でまず覚えるなら、次の2つで十分です。
- すべて更新する:
uv sync --upgrade - 1つだけ更新する:
uv sync --upgrade-package パッケージ名
これで、uv.lock と実際の環境をまとめて更新できます。
なぜ uv sync だけでは更新されないのか
uv は、uv.lock があると、そのロック済みバージョンを優先します。
そのため、単に uv sync するだけでは、「新しく公開された最新版」に自動更新されるわけではありません。
これは一見不便に見えますが、再現性のためには大切です。
昨日動いた環境を、今日も同じように再現しやすくなるからです。
すべてのライブラリを更新する
全部まとめて更新したいなら、次が分かりやすいです。
uv sync --upgrade
これは、ロックファイルを更新しつつ、環境も新しい状態へそろえます。
何が起きるのか
-
uv.lockが更新される - 許可された範囲で新しいバージョンが選ばれる
- 仮想環境もその内容に合わせて更新される
1つのライブラリだけ更新する
特定のパッケージだけ上げたいなら、次です。
uv sync --upgrade-package requests
この場合、requests は新しい版へ上がりますが、他のパッケージはなるべく現在のロックを維持します。
どんなときに便利か
- 特定ライブラリだけ脆弱性修正を入れたい
- 影響範囲を小さくしたい
- 一気に全部更新するのが不安
uv lock を使う考え方もある
更新は uv sync だけで進めてもよいですが、考え方としては次の2段階に分けることもできます。
-
uv lock --upgradeでロックファイルを更新する -
uv syncで環境へ反映する
すべて更新するなら:
uv lock --upgrade
uv sync
1つだけ更新するなら:
uv lock --upgrade-package requests
uv sync
uv lock と uv sync を分ける理由
- まずロックファイルの変化だけ見たい
- Git の差分を確認してから環境へ反映したい
- チーム開発で変更内容を見やすくしたい
個人開発なら uv sync --upgrade 系の方が手軽です。
チーム開発なら、uv lock と uv sync を分ける考え方も役立ちます。
上がらないときは何を見るか
更新コマンドを実行しても、思ったほど新しい版にならないことがあります。
その理由として多いのは、pyproject.toml 側の制約です。
たとえば、pyproject.toml に強い上限や固定バージョンがあると、その範囲を超えては更新されません。
そんなときは
依存条件自体を見直してから更新します。
uv add "requests>=2.32.0" --upgrade-package requests
これは、pyproject.toml の条件も見直しつつ、requests を新しい版へ更新したいときの書き方です。
更新前に知っておくと安心なこと
uv.lock は重要
ライブラリ更新では、uv.lock が大事です。
このファイルがあることで、「どこまで上がったか」「何が変わったか」を追いやすくなります。
更新後は動作確認する
ライブラリ更新は便利ですが、互換性の問題が出ることもあります。
更新後は、最低でも次のどちらかをした方が安心です。
- アプリを起動して確認する
- テストを実行する
いきなり全部更新しなくてもよい
不安なら、まずは1つだけ更新するやり方で十分です。
特に業務コードや長く動いているコードでは、その方が安全なことが多いです。
よくある流れ
1. とりあえず全部更新したい
uv sync --upgrade
2. requests だけ更新したい
uv sync --upgrade-package requests
3. 変更内容を先に見たい
uv lock --upgrade-package requests
uv sync
まとめ
今回のポイントは次のとおりです。
-
uv syncだけでは、新しく公開された版へ自動更新されない - 全更新なら
uv sync --upgrade - 個別更新なら
uv sync --upgrade-package パッケージ名 - 依存条件が厳しいと、思ったように上がらないことがある
- 更新後は
uv.lockの差分確認や動作確認をした方が安心
uv は「勝手に最新へしてしまう」よりも、「意図したときだけ上げる」方向のツールです。
最初は少し地味に見えますが、これがあとでかなり助かります。
参考
- uv Locking and syncing: https://docs.astral.sh/uv/concepts/projects/sync/
- uv Working on projects: https://docs.astral.sh/uv/guides/projects/
- uv Managing dependencies: https://docs.astral.sh/uv/concepts/projects/dependencies/
補足
この記事は生成AIを活用して作成しました。