Macで使うuv入門：Python環境構築と依存関係管理
Macでuvを導入し、Pythonバージョン管理、仮想環境、依存関係の追加、スクリプト実行まで行うためのガイド。
この記事でわかること
MacでPython環境をすばやく作り、プロジェクトごとに依存関係を整理するためのuv入門記事です。
- Macでuvを導入する方法
- Pythonバージョンと依存関係の管理
- スクリプト実行や同期コマンドの基本
おすすめ読者: MacでPython開発を始めたい人、pip/venvの管理を簡単にしたい人。
読む前の注意: コマンド、ライブラリ、モデルの仕様は環境やバージョンで変わります。実行前に手元の環境と公式情報を確認してください。
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で更新）
インストール方法の比較
| 項目 | 公式インストーラ | Homebrew |
|---|---|---|
| PATH 設定 | 自動 | 手動になる場合あり |
| アップデート | uv self update |
brew upgrade uv |
| バージョン追従 | 最新版が即リリース | Homebrew リリース日に依存 |
| 事前要件 | なし | Homebrew が必要 |
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 | shStep 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 の主な特徴・メリット
| 項目 | 説明 |
|---|---|
| 速度 | pip と比較して 10〜100倍高速。並列ダウンロード、グローバルキャッシュ、効率的な依存解決によって実現 |
| 単一ツール | pip / pyenv / virtualenv / poetry / pipx のすべてを置き換え可能 |
| スタンドバイナリ | Python や Rust なしでインストール可能 |
| ロックファイル | uv.lock で依存関係を厳密に固定。CI/CD 環境でも再現性確保 |
| バージョン管理 | uv python install / pin で Python バージョンを簡単に切り替え |
| ワークスペース対応 | Cargo スタイルのワークスペースで大規模プロジェクトも管理可能 |
| ディスク節約 | グローバルキャッシュで依存関係の重複を回避 |
| pip互換インターフェース | uv pip install で既存の pip コマンドを引き続き使用可能 |
7. よく使うコマンド一覧（リファレンス）
# インストール確認 uv --versionPython 管理
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 を読み込んで依存関係をインストール
参考サイト・記事
| タイトル | URL |
|---|---|
| Install uv · Mac Install Guide（公式手順書） | https://mac.install.guide/python/install-uv |
| uv for Python on Mac（Mac Install Guide） | https://mac.install.guide/python/uv |
| macOS に uv を入れて Python のパッケージ管理を行う | https://sig9.org/blog/2024/04/28/ |
| 最新のパッケージ管理ツール"UV"をインストールして使ってみた | https://note.com/noa813/n/nec941b514bca |
| uv完全ガイド - Python開発を爆速にする次世代ツール | https://timesaving.hatenablog.com/entry/2024/07/27/150000 |
| uv公式ドキュメント | https://docs.astral.sh/uv/ |
| How to Install and Use UV Package Manager on Windows and Mac | https://medium.com/@batoolarifa73/how-to-install-and-use-uv-package-manager-on-windows-and-mac-483f6f9de3c6 |
まとめ： uv は「1つのツールでPython開発を完全管理できる」次世代パッケージマネージャーです。Mac では公式インストーラか Homebrew のいずれかで簡単に導入でき、pip/pyenv/virtualenv などの複数のツールを使う煩雑さから解放されます。Rust で書かれたスタンドバイナリのため、パフォーマンスが非常に高く、10〜100倍の高速化を実現しています。
よくある質問
Homebrewと公式インストーラはどちらがよいですか？
普段からHomebrewで開発ツールを管理しているならHomebrew、uv単体で新しく試すなら公式インストーラが分かりやすいです。
既存のPython環境と衝突しますか？
プロジェクトごとに環境を分ければ衝突は抑えられます。PATHと使用中のPythonを確認しながら進めてください。
Linux版の記事も読むべきですか？
Macだけで完結するなら不要ですが、VPSやDockerで動かす予定があるならLinux版も読むと運用時の差分が分かります。
