🦔

uv を試してみる

に公開
Python
uv
tech

こんにちは

Pythonのパッケージ管理ツールとして uv をよく耳にするようになりました。
基礎的なキャッチアップと実際に環境を立ち上げて挙動を確認したいと思います。

uv公式: https://docs.astral.sh/uv/

An extremely fast Python package and project manager, written in Rust.

公式の推しポイントは「Rust製のめっちゃ速いPythonパッケージマネージャーやで」ということですね。

特徴

  • Rust製の超高速Pythonパッケージ管理ツール: pipやpoetryより10~100倍高速で、依存関係の解決とインストールを実行
  • オールインワンツール: パッケージ管理、仮想環境管理、Pythonバージョン管理を単一ツールで提供
  • モダンな開発体験: uv runで環境構築を意識せず実行でき、lockfileで再現性の高いプロジェクト管理を実現

インストール

以下は一例を記載。

Homebrewの場合

brew install uv

macOS/Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

プロジェクト作成・管理

# 新規プロジェクト作成
uv init my-project
cd my-project

# 仮想環境(.venvフォルダ作成)
uv venv

# ライブラリ追加
uv add pandas numpy

# 開発用のみにパッケージ追加(prodでは使用しないもの)
uv add --dev pytest black

# ライブラリ削除
uv remove numpy

# ライブラリ一覧
uv pip list

依存関係は pyproject.toml, uv.lockに反映される。
pip install library-name が uv add library-name になる感じですね。

依存関係管理

uv lock

役割:- 依存関係の解決のみ実行（インストールはしない）

  • pyproject.tomlを読み取り、依存関係を解決して uv.lockファイルを生成・更新
  • 新しいパッケージの組み合わせで競合がないか事前確認できる
  • CIやバージョン管理で lock ファイルのみ最新化したいときに使用できる
uv sync

役割: uv lock + インストールを実行する

  • まず依存関係を解決してuv.lockを更新し、その後実際に仮想環境へパッケージをインストールする
  • 開発環境をセットアップしたいときに使う
    プロダクト開発の現場視点では、チームメンバーが git pull をした後に uv sync を実行するだけで環境が整う。
  • uv sync --no-devを実行した場合は、開発環境用のみに指定されたパッケージ以外をインストールできる
uv tree

役割: インストールされている依存関係をツリー形式で表示

  • どのパッケージがどのパッケージに依存しているか視覚的に把握
  • 特定のパッケージがなぜインストールされているか調査可能
  • バージョン競合やサイズの大きい依存関係の特定に便利

Pythonバージョン管理


# 特定バージョンのPythonをインストール
uv python install 3.13

# プロジェクトで使用するバージョン指定
uv python pin 3.13

# インストール済みのバージョン確認
uv python list

コード実行

# 仮想環境を自動で作成して実行
uv run python main.py

# スクリプト実行
uv run pytest

ツールインストール

PythonのCLI ツール（black、ruff、pytestなど）をプロジェクトの依存関係とは分離してグローバルに管理できる

# ツールをインストール
uv tool install ruff
uv tool install black
uv tool install pytest

# インストール済みツールの一覧
uv tool list

# ツールの実行
ruff check .
black .

# ツールのアップデート
uv tool upgrade ruff

# ツールのアンインストール
uv tool uninstall ruff

チーム開発の場合は、uv add --dev でプロジェクト依存にすることでCIと開発環境でバージョンを一致させることができる

実務での使い分け

プロジェクト依存(uv add)

uv add --dev pytest black ruff
  • プロジェクトごとに異なるバージョンが必要
  • pyproject.tomlで管理して、チーム全体で統一
  • 仮想環境内にインストール

ツールインストール(uv tool install)

uv tool install black
  • 複数プロジェクトで共通して一般的なものとして使うツール
  • 個人の開発環境におけるバージョン管理
  • グローバルに利用したいもの

一時的な検証(uvx)

# まずは試す時、仮想環境を汚さずに一時的にキャッシュで実行
uvx run pytest

# 良さそうなら uv add --dev pytest

# キャッシュ削除
uc cache clean

(参考)Jupyter Labで挙動を確認する

Jupyter をインストールする

uv add jupyter

Jupyter Lab を仮想環境で起動する

uv run jupyter lab

pandas, numpy, matplotlibをインポートしてみる

matplotlibは追加していないので正しくエラーが返される。

再度、ターミナルにて uv add matplotlibを実行後に再起動して一連のライブラリの挙動を確認する。

まとめ

uv を使って無事に簡単な環境構築ができました！
基礎的な部分では特に難しいと感じる点はありませんでした。uvを使ってプロジェクトを進める中で躓く点があればまた記事にしたいと思います。

Discussion