uvでサードパーティ製ライブラリを管理する

はじめに

#

Pythonのパッケージ管理ツールuvの使用方法を解説するシリーズの第2段です。 uvでサードパーティ製ライブラリの追加・削除、およびバージョンを管理する方法を解説します。

検証環境は以下の通りです。

• Windows 10 Home 22H2
• uv 0.8.14

この記事では、uvの以下のコマンドについて解説します。

• uv add [PACKAGES]: パッケージ（ライブラリ）を仮想環境にインストールする。
  • uv add --dev [PACKAGES]: 開発用のグループdevにインストールする。
  • uv add --group <GROUP> [PACKAGES]: 任意のグループにインストールする。
  • uv add --optional <OPTIONAL> [PACKAGES]: オプションの依存関係としてインストールする。
• uv remove [PACKAGES]: ライブラリを仮想環境からアンインストールする。
• uv tree: ライブラリの依存関係を木構造で可視化する。

ライブラリ管理の基礎

#

始めにuvによるライブラリ管理の仕組みについて解説します。

インストール

#

uvの仮想環境にライブラリをインストールする場合、uv addコマンドを実行します。

uv add [PACKAGES]

複数のライブラリを指定したり、バージョンを指定することも可能です。

uv add flask pandas

uv add flask==3.1.2

なお、uv addコマンドにオプションを付けることによって、実行用ライブラリと開発用ライブラリを分けて管理することなどが可能です。 オプションの詳細については後述します。

アンインストール

#

仮想環境からライブラリをアンインストールする場合、uv removeコマンドを実行します。

uv remove [PACKAGES]

インストール時にオプションを付けた場合、uv removeコマンドにもオプションが必要な場合があります。

uv add --dev ruff
uv remove --dev ruff

ライブラリ管理のファイル

#

uvでは以下2つのファイルでライブラリを管理します。

• pyproject.toml
• uv.lock

各ファイルの違いを以下に記します。

pyproject.toml

#

pyproject.tomlでは、ユーザが作成するスクリプトが直接依存するライブラリのバージョンを管理します。 主にuvによって管理されますが、人の手で修正することも可能です。 ruff==0.12.11のようにバージョンを一意に指定することや、ruff>=0.12.11のように範囲指定することも可能です。

uv.lock

#

uv.lockは全ライブラリのバージョンを正確に記載するファイルです。 uvによって機械的に管理され、人の手で修正することは想定していません。 uv.lockがあることで、異なる仮想環境でも同じライブラリのバージョンをインストールできることが保障されます。 また、uv.lockはTOML形式となっています。

ライブラリの管理フィールド

#

uvではサードパーティ製ライブラリをグループでまとめたり、実行に必要なライブラリと開発に必要なライブラリで分けて管理することができます。 これらの区分は、pyproject.tomlで以下のように異なるフィールドで示されます。

# pyproject.toml
[project]
# 実行に必要なライブラリ
dependencies = [
  "httpx>=0.27.2",
]

[dependency-groups]
# グループとして管理するライブラリ
dev = [
  "pytest>=8.1.1, <9",
]

[project.optional-dependencies]
# オプションのライブラリ
plot = [
  "matplotlib>=3.6.3",
]

project.dependencies

#

project.dependenciesは最も基本となるライブラリのフィールドです。 以下のコマンドでライブラリをインストールすると、このフィールドに追加されます。

uv add [PACKAGES]

dependency-groups

#

dependency-groupsには、開発用ライブラリなどをグループにまとめて定義します。 dependency-groupsはPEP 735で公式に定義された仕様です。 グループ名にはdevやplotなど、任意の名前を定義できます。

# pyproject.toml
[dependency-groups]
# グループとして管理するライブラリ
dev = [
  "pytest>=8.1.1, <9",
]
doc = [
  "mkdocs>=1.6.1",
  "mkdocs-material>=9.6.18",
]

一般に、devには開発用ライブラリを定義します。 開発用ライブラリとは、開発者のみ使用するリンターや自動テスト用のライブラリ (ruff, pytest, mypyなど) のことです。 なお、devグループはuvにおいてオプションが用意されているなど、特別な意味を持ちます。

devグループにライブラリを追加する場合、--devオプションを付けます。

uv add --dev [PACKAGES]

dev以外のグループにライブラリを追加する場合、--group <GROUP>オプションを付けます。

uv add --group <GROUP> [PACKAGES]
# 例
# uv add --group doc mkdocs

project.optional-dependencies

#

project.optional-dependenciesのフィールドには、実行に必要ではあるが、デフォルトではユーザにインストールさせないライブラリを定義します。 デフォルトでインストールさせない理由としては、そのライブラリに依存する機能をごく一部のユーザしか利用しない、などが考えられます（例：Pandasにおけるopenpyxlライブラリ）。

project.optional-dependenciesにライブラリを追加する場合、--optional <OPTIONAL>オプションを付けます。

uv add --optional <OPTIONAL> [PACKAGES]
# 例：
# uv add --optional plot matplotlib

なお、project.optional-dependenciesに定義されたライブラリはextraと呼ばれます。

コマンドとフィールドの対比

#

インストール用コマンドuv addのオプションと、pyproject.tomlのフィールドの対比は以下のテーブルのようになります。

また、各フィールドに定義されたライブラリは、uv syncで環境を構築するときのインストールの有無も異なります。 以下のテーブルに、uv syncの主なオプションとフィールドの関係を示します（〇はインストールされます）。

他にもインストールを制御するオプションは多数あります。 group系のオプションはdependency-groupsのフィールドに、extra系のオプションはproject.optional-dependenciesのフィールドに関係しています。

ライブラリ依存関係の可視化

#

インストールしたライブラリを表示するには、uv treeコマンドを実行します。

> uv tree
Resolved 8 packages in 2ms
myapp v0.1.0
├── pytest v8.4.2
│   ├── colorama v0.4.6
│   ├── iniconfig v2.1.0
│   ├── packaging v25.0
│   ├── pluggy v1.6.0
│   └── pygments v2.19.2
└── ruff v0.13.1

ここで、第1階層のmyappは自分で作成したプロジェクトです。 その下のpytest, ruffはuv addで明示的にインストールしたライブラリになります。 これより下の階層は、付随してインストールしたライブラリです。

まとめ

#

• uv add [PACKAGES]: パッケージ（ライブラリ）を仮想環境にインストールする。
  • uv add --dev [PACKAGES]: 開発用のグループdevにインストールする。
  • uv add --group <GROUP> [PACKAGES]: 任意のグループにインストールする。
  • uv add --optional <OPTIONAL> [PACKAGES]: オプションの依存関係としてインストールする。
• uv remove [PACKAGES]: ライブラリを仮想環境からアンインストールする。
• uv tree: ライブラリの依存関係を木構造で可視化する。

参考

#

• Managing dependencies | uv