uv （pythonパッケージマネージャー）の使い方 簡易版

詳細版はこちら

読者が uvをシステム開発にすぐに応用できることを目指します。

• uv公式ドキュメント
• uv (github)

-1. なぜ uv なのか

• 名前の由来は UniVerse （宇宙！） とか UltraViolet （紫外線）とかっぽいんですが、実際のところ何が由来なのかわかりませんでした（参照）
• pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv といった従来のパッケージマネージャーを置き換えることができる！
• 公式曰く、extremely fast なパッケージマネージャーということで、 pip の 10 ～ 100 倍高速だそうです。poetry よりも15倍くらい早い！これは使うしかありませんね？

0. uvの基本的な使い方 (インストール済みという前提で)

uvの使い方は超簡単です。以下は、最も基本的な使い方の流れです。

新規プロジェクトの作成

uv init my-ml-project

依存関係の追加

uv add scikit-learn pandas matplotlib

スクリプトの実行

uv run my_ml_script.py

0.1. 使用感は poetry に似ているが、uvのメリットは大きい

uvの uv init, uv add, uv run という基本的なコマンドの流れは poetry に似ています。

poetryも、poetry new, poetry add, poetry run というコマンドで、プロジェクトの作成、依存関係の追加、スクリプトの実行を行います。

poetryは、依存関係の管理、仮想環境の管理、build、publish など、Pythonパッケージの開発に必要な機能を包括的に持っており、uvも同様の機能を備えています。

ただし、uvはpoetryよりも高速な動作、クロスプラットフォーム対応のロックファイル（素晴らしい...）、ワークスペースによる複数パッケージの管理など、いくつかの点で優位性があるそうです。

（poetry は linux系と windows でlockファイルの互換性が全然なかったりしましたがuvはどうなんでしょうね？未調査です）

uvは uv pip コマンドで、pip互換のインターフェースを提供しており、pipに慣れたユーザーはスムーズに移行することができます。

一方、poetryは豊富なドキュメント、活発なコミュニティなど成熟したパッケージマネージャーであり、安定性があります。

最終的にどちらのパッケージマネージャーが適しているかはいまのところ開発チームの好みでいい気がします。

1. uvのインストールとセットアップ

uvは、以下の方法でインストールできます。

• 公式インストーラー (推奨)

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

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

• pip

pip install uv

• Homebrew (macOS)

brew install uv

• Cargo

cargo install --git https://github.com/astral-sh/uv uv

インストール後、uv generate-shell-completion を実行してシェルに自動補完機能を追加することをお勧めします。

2. uvの基本的な使い方

uvのコマンド体系はシンプルで、直感的に操作できます。

• uv add: 依存関係を追加
• uv remove: 依存関係を削除
• uv sync: 環境を最新の状態に同期
• uv run: スクリプトを実行
• uv lock: ロックファイルを更新

3. uvによるプロジェクト管理

uvは、pyproject.toml で定義されたPythonプロジェクトを管理できます。

• uv init: 新規プロジェクトを作成
• uv add: 依存関係を追加
• uv remove: 依存関係を削除
• uv sync: 仮想環境を更新

プロジェクトの例

[project]
name = "my-ml-project"
version = "0.1.0"
requires-python = ">=3.8"
dependencies = [
    "scikit-learn",
    "pandas",
    "matplotlib",
]

[tool.uv.sources]
# 必要に応じて、Gitリポジトリやローカルパスなど、
# さまざまなソースからの依存関係を指定できます。

4. Dockerとの連携

uvはDockerとの連携が容易で、コンテナ化された機械学習アプリケーションの開発を効率化します。

Dockerfileの例

FROM python:3.9-slim

# uvをインストール
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

# プロジェクトをコピー
COPY . /app
WORKDIR /app

# 依存関係をインストール
RUN uv sync --frozen

# アプリケーションを実行
CMD ["uv", "run", "main.py"]

5. GitHub Actionsとの連携

uvは、GitHub Actionsと連携して、CI/CDパイプラインに統合できます。

workflowの例

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install uv
        uses: astral-sh/setup-uv@v3
      - name: Install dependencies
        run: uv sync --dev
      - name: Run tests
        run: uv run pytest

6. Jupyterとの連携

uvは、Jupyter Notebookと連携して、インタラクティブな機械学習開発をサポートします。

Jupyter Notebookでの使用例

# Jupyter Labを起動
uv run --with jupyter jupyter lab

# Notebook内でパッケージをインストール
!uv add pydantic

7. poetry, venv, pipからの移行

既存のpoetry, venv, pipプロジェクトをuvに移行するのは簡単です。

poetryからの移行

1. pyproject.toml をuvの形式に変換します。
2. poetry export -f requirements.txt --output requirements.txt で依存関係をエクスポートします。
3. uv pip install -r requirements.txt でuv環境に依存関係をインストールします。

venv, pipからの移行

1. pip freeze > requirements.txt で依存関係をエクスポートします。
2. uv venv で新しい仮想環境を作成します。
3. uv pip install -r requirements.txt で依存関係をインストールします。

参照

• uv公式ドキュメント
• uv (github)