uv （pythonパッケージマネージャー）の使い方 簡易版
読者が uvをシステム開発にすぐに応用できることを目指します。
-1. なぜ uv なのか
- 名前の由来は
UniVerse（宇宙！） とかUltraViolet（紫外線）とかっぽいんですが、実際のところ何が由来なのかわかりませんでした（参照） -
pip,pip-tools,pipx,poetry,pyenv,twine,virtualenvといった従来のパッケージマネージャーおよびPythonバージョン管理ツールを全てこれ一つで置き換えることができる！ -
公式曰く、
extremely fastなパッケージマネージャーということで、pipの 10 ～ 100 倍高速だそうです。poetryよりも圧倒的に早い！これは使うしかありませんね？
0. uvの基本的な使い方 (インストール済みという前提で)
uvの使い方は超簡単です。現在はプロジェクト管理機能が統合され、以下が標準的なフローです。
新規プロジェクトの作成
uv init my-ml-project
cd 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よりも圧倒的に高速であり、デフォルトでクロスプラットフォーム対応のロックファイル（uv.lock）を生成するため、Linux/Windows/macOS間での互換性トラブルがほぼありません。
また、Python自体のインストール・バージョン管理機能も内包しているため、pyenv も不要になります。
かつてはPoetryの方が成熟していましたが、2025年現在、uvは機能面でも安定性でもPoetryを置き換えるのに十分な水準に達しており、新規プロジェクトではuvの採用が推奨されます。
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
インストール後、シェルの設定ファイル（.bashrc や .zshrcなど）に自動補完の設定を追加することをお勧めします。
# 例: zshの場合
echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc
source ~/.zshrc
2. uvの基本的な使い方
uvのコマンド体系はシンプルで、直感的に操作できます。
-
uv add: 依存関係を追加（pyproject.tomlとuv.lockを更新） -
uv remove: 依存関係を削除 -
uv sync: ロックファイルに基づいて仮想環境を同期・作成 -
uv run: 仮想環境内でスクリプトやツールを実行 -
uv lock: ロックファイルのみを更新
3. uvによるプロジェクト管理
uvは、pyproject.toml で定義されたPythonプロジェクトを管理できます。
（uv init すると自動的にPEP 621準拠の pyproject.toml が生成されます）
プロジェクトの例 (pyproject.toml)
[project]
name = "my-ml-project"
version = "0.1.0"
requires-python = ">=3.9"
dependencies = [
"scikit-learn",
"pandas",
"matplotlib",
]
[tool.uv]
# 必要に応じて、Gitリポジトリやローカルパスなど、
# さまざまなソースからの依存関係を指定できます。
4. Dockerとの連携
uvはDockerとの連携が容易です。以下はマルチステージビルド等は省略したシンプルな例ですが、キャッシュを活用しつつ高速にビルドできます。
Dockerfileの例
FROM python:3.9-slim
# uvをインストール
COPY /uv /uvx /bin/
# アプリケーションのディレクトリを作成
WORKDIR /app
# 依存関係ファイルのコピー
COPY pyproject.toml uv.lock ./
# 依存関係をインストール
# --frozen: ロックファイル通りにインストール（更新しない）
# --no-dev: 開発用依存関係を含めない（本番用）
RUN uv sync --frozen --no-dev
# プロジェクトをコピー
COPY . .
# PATHを通すことで uv run を介さずに python コマンドで実行可能にする
ENV PATH="/app/.venv/bin:$PATH"
# アプリケーションを実行
CMD ["python", "main.py"]
5. GitHub Actionsとの連携
uvは、GitHub Actionsと連携して、CI/CDパイプラインに統合できます。公式のアクションを使用するのが便利です。
workflowの例
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install uv
# 最新版（v5系など）を指定
uses: astral-sh/setup-uv@v5
with:
version: "latest"
enable-cache: true # キャッシュを有効化
- name: Install dependencies
# uv sync はデフォルトで dev dependencies もインストールします
run: uv sync
- name: Run tests
run: uv run pytest
6. Jupyterとの連携
uvは、Jupyter Notebookと連携して、インタラクティブな機械学習開発をサポートします。
Jupyter Notebookでの使用例
# プロジェクト内にJupyterをインストール
uv add --dev jupyterlab
# 仮想環境を使ってJupyter Labを起動
uv run jupyter lab
# Notebook内でパッケージを追加したい場合
# （注: Notebook内から実行する場合、カーネルの再起動が必要なことがあります）
!uv add pydantic
7. poetry, venv, pipからの移行
既存のプロジェクトをuvに移行する方法です。
poetryからの移行
-
pyproject.tomlの[tool.poetry]セクション等はuv（標準のPEP 621）と互換性がありません。 - 一旦
requirements.txtを吐き出すのが手っ取り早いです。poetry export -f requirements.txt --output requirements.txt - uvで初期化し、依存関係を取り込みます。
uv init uv add -r requirements.txt
venv, pipからの移行
- 既存環境の依存関係をエクスポートします。
pip freeze > requirements.txt - uvでプロジェクトを初期化し、依存関係を取り込みます。これで
uv init uv add -r requirements.txtpyproject.tomlとuv.lockが生成され、モダンな管理環境が整います。
Discussion