Mac で使う uv（Python パッケージマネージャー）完全ガイド

1. uv とは

uv（Ultra-fast universal package installer） は、Astral（Ruff Linter開発元）によって Rust で開発された 超高速の Python パッケージ・プロジェクト管理ツール です。

従来、Python 開発には複数のツールを使い分ける必要がありました：
– pip … パッケージインストール
– pyenv … Python バージョン管理
– virtualenv … 仮想環境の作成
– poetry / rye … プロジェクト依存関係管理
– pipx … CLI ツールのグローバルインストール

uv はこれら すべてを単一ツールに置き換える ことを目的としており、10〜100倍の速度向上を実現しています。

2. Mac へのインストール方法

方法①：公式インストーラ（推奨）

Astral 開発元が推奨するインストール方法です。Python や Homebrew の事前インストールは不要です。

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

動作内容：
– ~/.local/bin に uv と uvx バイナリをインストール
– ~/.zshenv を自動修正し、PATH に ~/.local/bin を追加
– $HOME/.local/bin/env ファイルを作成（現在のセッションで uv を有効化）

# 設定を反映（ターミナル再起動不要の場合）
source $HOME/.local/bin/env

# インストール確認
uv --version

方法②：Homebrew 経由

すでに Homebrew を使っている場合はこちらが便利です。

brew install uv

どちらを選ぶべきか：
– 最新バージョンをすぐ導入したい → 公式インストーラ（uv self updateで自動更新）
– Homebrew パッケージとともに管理したい → brew install uv（brew upgrade uv で更新）

インストール方法の比較

3. 基本的な使い方

プロジェクトの初期化

# 新しいプロジェクトを作成（pyproject.toml が自動生成される）
uv init myproject
cd myproject

# 既存ディレクトリで初期化
uv init

Python バージョンの管理

# Python の全バージョン一覧を表示
uv python list

# インストール済みのバージョンのみ表示
uv python list --only-installed

# 最新の安定版をインストール
uv python install

# 特定のバージョンをインストール
uv python install 3.12
uv python install 3.10 3.11 3.12    # 複数同時にも対応

# PyPy などの代替実装もインストール可能
uv python install pypy3.10

# プロジェクトで特定の Python バージョンを指定（.python-version が作成）
uv python pin 3.12

パッケージの依存関係管理

# パッケージを追加（pyproject.toml を自動更新 + .venv にインストール）
uv add requests
uv add "fastapi>=0.100.0"
uv add "django~=4.2"
uv add pytest --dev    # 開発用依存関係として追加

# requirements.txt から一括インストール
uv pip install -r requirements.txt

仮想環境の操作

# .venv という名前の仮想環境を作成
uv venv

# 特定の Python バージョンで仮想環境を作成
uv venv --python 3.12

# 仮想環境を有効化
source .venv/bin/activate

プロジェクト依存関係の同期

# pyproject.toml や uv.lock に記載された依存関係をすべてインストール
uv sync

スクリプトの実行

# プロジェクト環境内でスクリプトを実行
uv run python script.py
uv run main.py

# テストも同じコマンドで実行可能
uv run pytest
uv run python -c "import requests; print('OK')"

ツールの実行（uvx）

# 一時的な環境で ruff を実行（インストール不要）
uvx ruff check .

# ツールを恒久的にインストール
uv tool install ruff

4. macOS 特有の注意点

PATH の設定

公式インストーラを使用した場合、~/.zshenv は自動的に修正されます。PATH が通っているか確認：

echo $PATH
# ~/.local/bin が含まれていることを確認

手動で PATH を設定する必要がある場合（Homebrew 導入時など）：

# ~/.zprofile または ~/.zshenv に追加
export PATH="$HOME/.local/bin:$PATH"
source ~/.zprofile

Apple Silicon (Mシリーズ) と Intel 系Macの違い

• 公式インストーラ：プロセッサ種別に関係なく ~/.local/bin にインストール
• Homebrew：
• Apple Silicon → /opt/homebrew/bin
• Intel Mac → /usr/local/bin

Xcode Command Line Tools の事前インストール

xcode-select -p    # パスが表示されればOK

表示されない場合は事前にインストール：

xcode-select --install

5. uv を使った開発ワークフロー例

# Step 1: uv のインストール
curl -LsSf https://astral.sh/uv/install.sh | sh

# Step 2: プロジェクト作成
mkdir myproject && cd myproject
uv init
uv python pin 3.12    # Python 3.12 を指定

# Step 3: パッケージ追加
uv add requests
uv add "fastapi>=0.100.0"
uv add pytest --dev

# Step 4: 仮想環境の同期
uv sync

# Step 5: スクリプト実行
uv run python script.py

6. uv の主な特徴・メリット

7. よく使うコマンド一覧（リファレンス）

# インストール確認
uv --version

# Python 管理
uv python list                  # 全バージョン表示
uv python list --only-installed # インストール済み表示
uv python install 3.12          # バージョンインストール
uv python find                  # デフォルトのPythonを表示
uv python dir                   # Python保存先ディレクトリ
uv python pin 3.12              # プロジェクトでバージョン指定

# プロジェクト管理
uv init myproject               # プロジェクト生成
uv add <package>                # パッケージ追加
uv sync                         # 依存関係一括インストール
uv lock                         # ロックファイル生成

# 仮想環境
uv venv                         # .venv を作成
uv venv --python 3.12           # 特定バージョンで仮想環境

# スクリプト実行
uv run python script.py         # プロジェクト環境内で実行
uv run pytest                   # テスト実行

# ツール
uvx ruff check .                # 一時的にツールを実行
uv tool install ruff            # ツールを恒久インストール

# パイプライン（pip互換）
uv pip install requests         # pip install の代替
uv pip compile requirements.in -o requirements.txt

8. uv のアップデート方法

公式インストーラ版の場合

uv self update    # uv を最新バージョンに自動更新

Homebrew 版の場合

brew upgrade uv   # Homebrew経由で更新

注意： Homebrew版で uv self update を実行したり、その逆をしたりすると、インストール方法が混在して問題が発生する可能性があります。

9. アンインストール方法

# キャッシュとデータ削除（任意）
uv cache clean
rm -r "$(uv python dir)"
rm -r "$(uv tool dir)"

# 公式インストーラ版の場合
rm ~/.local/bin/uv ~/.local/bin/uvx

# Homebrew 版の場合
brew uninstall uv

# shell設定ファイルの PATH エントリ削除（必要に応じて）
# ~/.zshenv または ~/.zprofile を編集

10. 参考：Rye から uv への移行

Rye は Astral の Charlie Marsh が以前に開発したプロジェクト管理ツールで、現在はメンテナンスモードです。uv が後継として推奨されています。

既存の Rye プロジェクトからの移行は単純で、プロジェクトディレクトリで以下を実行するだけです：

cd myproject
uv sync    # pyproject.toml を読み込んで依存関係をインストール

参考サイト・記事

まとめ： uv は「1つのツールでPython開発を完全管理できる」次世代パッケージマネージャーです。Mac では公式インストーラか Homebrew のいずれかで簡単に導入でき、pip/pyenv/virtualenv などの複数のツールを使う煩雑さから解放されます。Rust で書かれたスタンドバイナリのため、パフォーマンスが非常に高く、10〜100倍の高速化を実現しています。