Pythonのパッケージ管理ツール「uv」の使い方まとめ

2025年11月11日2025年11月12日

uvとはRuffを開発したAstralが開発したパッケージ管理・プロジェクト管理ツールです。

最近はvenvなどよりもuvを使ってパッケージを管理するプロジェクトも多いかと思うので、今回はuvの特徴と基本的な使い方についてまとめようと思います。

リンク

uv まとめ

公式ドキュメント

公式ドキュメントは以下になります。

uvの特徴

uvの特徴は以下になります。

高速性：依存解決や仮想環境の作成が非常に速い
操作性：簡単なコマンドでパッケージの管理を行える
既存ツールとの互換性：pip互換のIFを備えているため、既存のrequirements.txtやpyproject.tomlから移行しやすい

基本的な使い方

ここからは実際に基本的なuvの使い方をご紹介します。

uvのインストール

uvを使用するにはuvをインストールする必要があります。uvのインストールコマンドは以下になります。

wget -qO- https://astral.sh/uv/install.sh | sh

uvのバージョン確認

インストールしたuvのバージョンを確認するコマンドは以下になります。

uv self version
# uv 0.9.3 (83635a6c4 2025-10-15)

uvのアップデート

インストールしたuvをアップデートするコマンドは以下になります。

uv self update
# info: Checking for updates...
# success: Upgraded uv from v0.9.3 to v0.9.8! https://github.com/astral-sh/uv/releases/tag/0.9.8

Pythonプロジェクトの作成(uv initコマンド)

uvを使ってPythonパッケージを管理するプロジェクトを作成するコマンドは以下になります。

uv init <プロジェクト名>
# ls <プロジェクト名>
# main.py		pyproject.toml	README.md

uv initコマンドを実行すると、<プロジェクト名>で指定したフォルダが作成されます。
作成されたフォルダの中にはmain.pyやpyproject.toml、README.mdが自動で作成されます。

パッケージの追加(uv addコマンド)

作成したPythonプロジェクトで使いたいパッケージを追加するコマンドは以下になります。

uv add pandas
# Using CPython 3.12.8 interpreter at: /Users/edaha/.pyenv/versions/3.12.8/bin/python3.12
# Creating virtual environment at: .venv
# Resolved 7 packages in 260ms
# Prepared 5 packages in 361ms
# Installed 6 packages in 22ms
#  + numpy==2.3.4
#  + pandas==2.3.3
#  + python-dateutil==2.9.0.post0
#  + pytz==2025.2
#  + six==1.17.0
# + tzdata==2025.2

コマンドを実行すると、依存関係等を管理する設定ファイルであるpyproject.tomlのdependenciesキーにpandsの情報が追加されます。

パッケージの削除(uv removeコマンド)

uv addコマンドで追加したパッケージを削除するコマンドは以下になります。

uv remove pandas
# Resolved 1 package in 17ms
# Uninstalled 6 packages in 194ms
#  - numpy==2.3.4
#  - pandas==2.3.3
#  - python-dateutil==2.9.0.post0
#  - pytz==2025.2
#  - six==1.17.0

Pythonファイルの実行(uv runコマンド)

uvを使ってPythonのパッケージ管理をしているプロジェクトで、Pythonファイルを実行するコマンドは以下になります。

uv run main.py

uv runコマンドを実行することで、uv addなどで追加したパッケージを使ってPythonファイルを実行することができます。

補足：uv.lockファイル

説明が長くなるかと思い省略しましたが、uv addコマンドやuv runコマンドを実行するとuv.lockファイルというロックファイルが作成されます。

このロックファイルの中身は以下のようになっており、下の例ではnumpyをインストールするのに使用したwheelファイルなどの詳細が記載されています。

version = 1
revision = 3
requires-python = ">=3.12"

[[package]]
name = "numpy"
version = "2.3.4"
source = { registry = "https://pypi.org/simple" }
sdist = { url = "https://files.pythonhosted.org/packages/b5/f4/098d2270d52b41f1bd7db9fc288aaa0400cb48c2a3e2af6fa365d9720947/numpy-2.3.4.tar.gz", hash = "sha256:a7d018bfedb375a8d979ac758b120ba846a7fe764911a64465fd87b8729f4a6a", size = 20582187, upload-time = "2025-10-15T16:18:11.77Z" }
wheels = [
    { url = "https://files.pythonhosted.org/packages/96/7a/02420400b736f84317e759291b8edaeee9dc921f72b045475a9cbdb26b17/numpy-2.3.4-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:ef1b5a3e808bc40827b5fa2c8196151a4c5abe110e1726949d7abddfe5c7ae11", size = 20957727, upload-time = "2025-10-15T16:15:44.9Z" },
    { url = "https://files.pythonhosted.org/packages/18/90/a014805d627aa5750f6f0e878172afb6454552da929144b3c07fcae1bb13/numpy-2.3.4-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:c2f91f496a87235c6aaf6d3f3d89b17dba64996abadccb289f48456cff931ca9", size = 14187262, upload-time = "2025-10-15T16:15:47.761Z" },
...
    { url = "https://files.pythonhosted.org/packages/54/23/08c002201a8e7e1f9afba93b97deceb813252d9cfd0d3351caed123dcf97/numpy-2.3.4-cp314-cp314t-win_arm64.whl", hash = "sha256:8b5a9a39c45d852b62693d9b3f3e0fe052541f804296ff401a72a1b60edafb29", size = 10547532, upload-time = "2025-10-15T16:17:53.48Z" },
]

...

で、このロックファイルがあると何が嬉しいかというと、このロックファイルの作成元であるPythonプロジェクトを完全に再現することができる点です。

ロックファイルの中には各パッケージをインストールするのに使用したurlなどが記載されているので、ロックファイルがあるフォルダ内でuv syncというコマンドを打つだけで、全く同じ環境を作成することができるわけです。

そのため、都度都度パッケージの依存関係を確認しながら環境構築をする手間がなくなるわけです。これは素晴らしい。