macOS で Python 開発を始めたいけれど、バージョン管理やパッケージ管理で悩んでいませんか？システムの Python を触って環境を壊してしまった経験がある方も多いのではないでしょうか。

この記事では、macOS における Python 環境構築の決定版として、pyenv、uv、Rye の 3 つのツールを使った最小ストレスな開発環境の作り方をご紹介します。それぞれのツールが持つ強みを理解し、用途に応じて使い分けることで、快適な Python 開発ライフが実現できますよ。

背景

macOS における Python 環境の複雑さ

macOS には標準で Python がインストールされていますが、これをそのまま開発に使うのは推奨されません。システムの Python を直接使うと、OS の動作に影響を与えるリスクがあるためです。

また、複数のプロジェクトで異なる Python バージョンやパッケージが必要になることは日常茶飯事ですよね。プロジェクト A では Python 3.9 と Django 3.2、プロジェクト B では Python 3.11 と FastAPI という具合に、環境を切り替える必要が出てきます。

mermaidCopy codeflowchart TB
  sys["macOS システム Python<br/>(触ってはいけない)"]
  dev["開発用 Python 環境<br/>(独立して管理)"]
  pjA["プロジェクト A<br/>Python 3.9 + Django"]
  pjB["プロジェクト B<br/>Python 3.11 + FastAPI"]
  pjC["プロジェクト C<br/>Python 3.12 + Flask"]

  sys -.->|分離| dev
  dev --> pjA
  dev --> pjB
  dev --> pjC

図で理解できる要点：

• システム Python と開発環境は完全に分離すべき
• 複数プロジェクトごとに異なる Python バージョン・パッケージが必要
• 環境管理ツールで柔軟に切り替え可能にする

Python 環境管理ツールの進化

Python のエコシステムは日々進化しており、環境管理ツールも多様化しています。従来の virtualenv や venv から、より高機能な pyenv、そして最新の uv や Rye まで、選択肢が豊富になりました。

それぞれのツールには明確な役割があります。pyenv は Python バージョンの管理、uv は超高速なパッケージ管理、Rye はプロジェクト全体の統合管理を得意としています。

課題

従来の環境構築における問題点

従来の Python 環境構築では、いくつかの課題が開発者を悩ませてきました。

Python バージョン管理の煩雑さ

公式インストーラーで Python をインストールすると、バージョンの切り替えが面倒です。複数バージョンを共存させようとすると、PATH の設定が複雑になり、意図しないバージョンが起動してしまうことも。

#	課題	具体例	影響
1	バージョン切り替えの手間	PATH を手動で書き換える必要がある	作業効率の低下
2	複数バージョンの共存が困難	インストール場所の管理が煩雑	環境の混乱
3	アンインストールの残骸	古いバージョンのファイルが残る	ディスク容量の無駄

パッケージ管理の遅さ

pip は広く使われていますが、大量のパッケージをインストールする際の速度が課題でした。依存関係の解決にも時間がかかり、プロジェクトのセットアップに数分待たされることもありますよね。

プロジェクト設定の散在

プロジェクトごとに requirements.txt、setup.py、pyproject.toml など、複数の設定ファイルを管理する必要があり、どこに何を書けばいいのか迷うことも多いでしょう。

mermaidCopy codeflowchart LR
  dev["開発者"] -->|"どれを使う?"| choice{"設定ファイル選択"}
  choice -->|従来型| req["requirements.txt"]
  choice -->|パッケージング| setup["setup.py"]
  choice -->|モダン| pyproj["pyproject.toml"]
  choice -->|詩的管理| poetry["poetry.lock"]

  req -.->|問題| prob1["バージョン固定が弱い"]
  setup -.->|問題| prob2["記述が複雑"]
  pyproj -.->|問題| prob3["ツールごとに形式が違う"]

図で理解できる要点：

• 設定ファイルの種類が多く選択に迷う
• それぞれに異なる問題点がある
• 統一された管理方法が求められている

macOS 特有の注意点

macOS では、M1/M2/M3 チップ（Apple Silicon）と Intel チップで異なるアーキテクチャに対応する必要があります。一部のパッケージはアーキテクチャによってインストール方法が変わることもあり、注意が必要です。

また、macOS のシステム整合性保護（SIP）により、システムディレクトリへの書き込みが制限されているため、適切な場所に Python 環境を構築することが重要になります。

解決策

pyenv：Python バージョン管理の決定版

pyenv は、複数の Python バージョンを簡単に管理できるツールです。インストールからバージョン切り替えまで、コマンド一つで完結します。

pyenv のインストール

Homebrew を使って pyenv をインストールしましょう。Homebrew は macOS の定番パッケージマネージャーですね。

bashCopy code# Homebrew で pyenv をインストール
brew install pyenv

インストール後、シェルの設定ファイルに pyenv の初期化コードを追加します。zsh を使っている場合は .zshrc に記述しますよ。

bashCopy code# zsh の場合（~/.zshrc に追記）
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init --path)"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc

設定を反映させるために、ターミナルを再起動するか以下のコマンドを実行してください。

bashCopy code# 設定を即座に反映
source ~/.zshrc

Python バージョンのインストールと切り替え

pyenv で利用可能な Python バージョンを確認し、必要なバージョンをインストールします。

bashCopy code# インストール可能なバージョン一覧を表示
pyenv install --list

特定のバージョンをインストールする際は、バージョン番号を指定するだけです。

bashCopy code# Python 3.11.6 をインストール
pyenv install 3.11.6

# Python 3.12.0 もインストール
pyenv install 3.12.0

グローバル（システム全体）で使用する Python バージョンを設定できます。

bashCopy code# グローバルで使用する Python を設定
pyenv global 3.11.6

# 現在のバージョンを確認
python --version
# 出力: Python 3.11.6

プロジェクトごとに異なるバージョンを使いたい場合は、ローカル設定が便利です。

bashCopy code# プロジェクトディレクトリで実行
cd ~/projects/my-project
pyenv local 3.12.0

# このディレクトリ内では Python 3.12.0 が使われる
python --version
# 出力: Python 3.12.0

#	コマンド	用途	スコープ
1	pyenv global	システム全体のデフォルト設定	グローバル
2	pyenv local	プロジェクト固有の設定	ディレクトリ単位
3	pyenv shell	現在のシェルセッションのみ	セッション単位

uv：爆速パッケージ管理ツール

uv は Rust で書かれた次世代パッケージマネージャーで、pip の 10〜100 倍高速と言われています。依存関係の解決とインストールが驚くほど速いのが特徴です。

uv のインストール

uv も Homebrew で簡単にインストールできます。

bashCopy code# Homebrew で uv をインストール
brew install uv

または、公式のインストールスクリプトを使う方法もあります。

bashCopy code# 公式スクリプトでインストール
curl -LsSf https://astral.sh/uv/install.sh | sh

uv による仮想環境の作成

uv を使って Python 仮想環境を作成します。従来の venv よりも高速に作成できますよ。

bashCopy code# 仮想環境を作成（.venv ディレクトリに作成）
uv venv

# 仮想環境を有効化（macOS/Linux）
source .venv/bin/activate

仮想環境が有効化されると、プロンプトに (.venv) が表示されます。この状態でインストールしたパッケージは、この仮想環境内にのみ影響します。

パッケージのインストール

uv を使ったパッケージインストールは非常に高速です。pip と同じ感覚で使えます。

bashCopy code# パッケージを個別にインストール
uv pip install requests

# 複数パッケージを同時にインストール
uv pip install fastapi uvicorn sqlalchemy

requirements.txt からのインストールも、従来の pip より圧倒的に速く完了します。

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

依存関係の出力も uv で行えます。

bashCopy code# 現在の環境の依存関係を出力
uv pip freeze > requirements.txt

mermaidCopy codesequenceDiagram
  participant Dev as 開発者
  participant UV as uv
  participant PyPI as PyPI リポジトリ
  participant Env as 仮想環境

  Dev->>UV: uv pip install requests
  UV->>PyPI: パッケージ情報取得
  PyPI-->>UV: メタデータ返却
  UV->>UV: 依存関係解決<br/>(超高速)
  UV->>PyPI: パッケージダウンロード
  PyPI-->>UV: パッケージファイル
  UV->>Env: インストール実行
  Env-->>Dev: 完了通知

図で理解できる要点：

• uv は依存関係解決が高速
• PyPI との通信を最適化
• 仮想環境へのインストールまで一貫して高速

Rye：統合プロジェクト管理ツール

Rye は、Python プロジェクトの管理を一元化するツールです。Python のインストール、仮想環境の作成、パッケージ管理をすべて Rye だけで完結できます。

Rye のインストール

Rye のインストールは公式スクリプトを使うのが推奨されています。

bashCopy code# Rye をインストール
curl -sSf https://rye.astral.sh/get | bash

インストール後、シェル設定ファイルに Rye のパスを追加します。

bashCopy code# zsh の場合（~/.zshrc に追記）
echo 'source "$HOME/.rye/env"' >> ~/.zshrc

# 設定を反映
source ~/.zshrc

Rye が正しくインストールされたか確認しましょう。

bashCopy code# Rye のバージョン確認
rye --version

Rye によるプロジェクト初期化

Rye でプロジェクトを初期化すると、必要な設定ファイルが自動生成されます。

bashCopy code# 新しいプロジェクトを作成
rye init my-project

# プロジェクトディレクトリに移動
cd my-project

プロジェクトディレクトリには、以下のファイルが自動生成されます。

perlCopy codemy-project/
├── .python-version    # Python バージョン指定
├── pyproject.toml     # プロジェクト設定
├── README.md          # プロジェクト説明
└── src/
    └── my_project/
        └── __init__.py

Python バージョンの指定とパッケージ管理

Rye では、プロジェクトごとに使用する Python バージョンを指定できます。

bashCopy code# Python 3.11 を使用するよう設定
rye pin 3.11

このコマンドを実行すると、.python-version ファイルが更新され、指定したバージョンの Python が自動でインストールされます。

パッケージの追加も Rye で一元管理できます。

bashCopy code# パッケージを追加
rye add fastapi uvicorn

# 開発時のみ必要なパッケージを追加
rye add --dev pytest black

追加したパッケージは pyproject.toml に自動記録され、依存関係が明確になります。

tomlCopy code# pyproject.toml の一部
[project]
name = "my-project"
version = "0.1.0"
dependencies = [
    "fastapi>=0.104.0",
    "uvicorn>=0.24.0",
]

[tool.rye]
dev-dependencies = [
    "pytest>=7.4.0",
    "black>=23.10.0",
]

依存関係をインストールして環境を整えます。

bashCopy code# 依存関係をすべてインストール
rye sync

Rye で管理されている Python を実行する際は、rye run を使います。

bashCopy code# スクリプトを実行
rye run python src/my_project/main.py

# pytest を実行
rye run pytest

3 つのツールの使い分け

それぞれのツールには得意分野があり、状況に応じて使い分けるのが賢明です。

#	ツール	主な用途	推奨シーン
1	pyenv	Python バージョン管理	複数バージョンを切り替えながら開発
2	uv	高速パッケージ管理	大規模プロジェクトや CI/CD 環境
3	Rye	統合プロジェクト管理	新規プロジェクトの立ち上げから運用まで

pyenv を選ぶべき場合：

• 既存プロジェクトで Python バージョンだけ管理したい
• 他のパッケージマネージャー（Poetry など）と組み合わせたい
• システム全体で複数の Python バージョンを使い分けたい

uv を選ぶべき場合：

• インストール速度を最優先したい
• CI/CD パイプラインでビルド時間を短縮したい
• pip との互換性を保ちながら高速化したい

Rye を選ぶべき場合：

• プロジェクト全体を一つのツールで管理したい
• 設定ファイルの散在を避けたい
• チーム開発で環境の一貫性を保ちたい

具体例

pyenv を使った複数バージョン管理の実例

実際のプロジェクトで pyenv を使ってバージョンを管理する流れを見てみましょう。

既存プロジェクトへの適用

既存のプロジェクトに pyenv を導入するケースを考えます。プロジェクト A では Python 3.9、プロジェクト B では Python 3.11 を使うとしましょう。

bashCopy code# プロジェクト A に移動
cd ~/projects/project-a

# Python 3.9.18 をインストール
pyenv install 3.9.18

# プロジェクト A で Python 3.9.18 を使用
pyenv local 3.9.18

# 確認
python --version
# 出力: Python 3.9.18

続いてプロジェクト B に移動します。

bashCopy code# プロジェクト B に移動
cd ~/projects/project-b

# Python 3.11.6 をインストール
pyenv install 3.11.6

# プロジェクト B で Python 3.11.6 を使用
pyenv local 3.11.6

# 確認
python --version
# 出力: Python 3.11.6

それぞれのプロジェクトディレクトリに .python-version ファイルが作成され、ディレクトリに入るだけで自動的に適切なバージョンに切り替わります。

チーム開発での活用

チームメンバー全員が同じ Python バージョンを使うために、.python-version ファイルをリポジトリに含めます。

bashCopy code# .python-version ファイルをコミット
git add .python-version
git commit -m "Add Python version specification"
git push origin main

他のメンバーがリポジトリをクローンした際、pyenv が自動的に適切なバージョンを使用します。

bashCopy code# 他のメンバーがクローン
git clone https://github.com/team/project-a.git
cd project-a

# pyenv が .python-version を読み取り、
# 必要なら自動インストールを促す
python --version

uv を使った高速環境構築の実例

uv の速度を活かした開発フローを見ていきます。

大規模プロジェクトのセットアップ

Django や TensorFlow など、依存関係が多いプロジェクトでは、uv の速度が際立ちます。

bashCopy code# プロジェクトディレクトリを作成
mkdir django-project
cd django-project

# uv で仮想環境を作成
uv venv

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

requirements.txt を用意して、一括インストールします。

textCopy code# requirements.txt
Django==4.2.7
djangorestframework==3.14.0
celery==5.3.4
redis==5.0.1
psycopg2-binary==2.9.9
pillow==10.1.0

uv で高速インストールを実行します。

bashCopy code# uv を使って高速インストール
uv pip install -r requirements.txt

# 通常の pip より 10〜100 倍高速

インストールが完了したら、Django プロジェクトを開始できます。

bashCopy code# Django プロジェクトを作成
django-admin startproject mysite .

# 開発サーバーを起動
python manage.py runserver

CI/CD での活用

GitHub Actions で uv を使うと、ビルド時間を大幅に短縮できます。

yamlCopy code# .github/workflows/test.yml
name: Test

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      # リポジトリをチェックアウト
      - uses: actions/checkout@v4

      # Python をセットアップ
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      # uv をインストール
      - name: Install uv
        run: curl -LsSf https://astral.sh/uv/install.sh | sh

      # 依存関係を高速インストール
      - name: Install dependencies
        run: |
          uv venv
          source .venv/bin/activate
          uv pip install -r requirements.txt

      # テストを実行
      - name: Run tests
        run: |
          source .venv/bin/activate
          pytest

このワークフローでは、uv により依存関係のインストール時間が大幅に短縮され、CI/CD の実行時間が削減されます。

Rye を使った統合管理の実例

Rye でプロジェクトを一元管理する実践例を見ていきましょう。

FastAPI プロジェクトの立ち上げ

FastAPI を使った REST API プロジェクトを Rye で構築します。

bashCopy code# Rye でプロジェクトを初期化
rye init fastapi-demo
cd fastapi-demo

# Python 3.11 を指定
rye pin 3.11

必要なパッケージを追加します。

bashCopy code# FastAPI と関連パッケージを追加
rye add fastapi uvicorn sqlalchemy pydantic-settings

# 開発用ツールを追加
rye add --dev pytest httpx black ruff

依存関係を同期してインストールします。

bashCopy code# 依存関係をインストール
rye sync

FastAPI のアプリケーションコードを作成します。

pythonCopy code# src/fastapi_demo/main.py
from fastapi import FastAPI

# FastAPI アプリケーションを初期化
app = FastAPI(title="FastAPI Demo")

# ルートエンドポイント
@app.get("/")
async def root():
    """
    ルートパスへのGETリクエストを処理
    """
    return {"message": "Hello, World!"}

# ヘルスチェックエンドポイント
@app.get("/health")
async def health():
    """
    アプリケーションの稼働状態を確認
    """
    return {"status": "healthy"}

Rye でアプリケーションを起動します。

bashCopy code# uvicorn で開発サーバーを起動
rye run uvicorn fastapi_demo.main:app --reload

ブラウザで http:​/​​/​localhost:8000 にアクセスすると、API が動作していることを確認できます。

テストとコード品質管理

開発用に追加した pytest と black を使って、テストとコード整形を行います。

pythonCopy code# tests/test_main.py
from fastapi.testclient import TestClient
from fastapi_demo.main import app

# テストクライアントを作成
client = TestClient(app)

def test_root():
    """
    ルートエンドポイントのテスト
    """
    response = client.get("/")
    assert response.status_code == 200
    assert response.json() == {"message": "Hello, World!"}

def test_health():
    """
    ヘルスチェックエンドポイントのテスト
    """
    response = client.get("/health")
    assert response.status_code == 200
    assert response.json() == {"status": "healthy"}

Rye でテストを実行します。

bashCopy code# pytest を実行
rye run pytest

# カバレッジ付きで実行
rye run pytest --cov=fastapi_demo

コードを自動整形するには black を使います。

bashCopy code# black でコード整形
rye run black src/ tests/

# ruff でリント
rye run ruff check src/ tests/

スクリプトの登録

よく使うコマンドは、pyproject.toml にスクリプトとして登録できます。

tomlCopy code# pyproject.toml に追記
[tool.rye.scripts]
dev = "uvicorn fastapi_demo.main:app --reload"
test = "pytest --cov=fastapi_demo"
lint = "ruff check src/ tests/"
format = "black src/ tests/"

登録したスクリプトは、短いコマンドで実行できます。

bashCopy code# 開発サーバー起動
rye run dev

# テスト実行
rye run test

# リント実行
rye run lint

# フォーマット実行
rye run format

mermaidCopy codeflowchart TD
  init["rye init プロジェクト"] --> pin["rye pin Python バージョン"]
  pin --> add["rye add パッケージ追加"]
  add --> sync["rye sync 依存関係同期"]
  sync --> code["コード実装"]
  code --> script["pyproject.toml<br/>スクリプト登録"]
  script --> dev["rye run dev<br/>開発サーバー起動"]
  script --> test["rye run test<br/>テスト実行"]
  script --> lint["rye run lint<br/>コード品質チェック"]

図で理解できる要点：

• Rye はプロジェクト初期化から運用まで一貫したフロー
• スクリプト登録で頻繁なコマンドを簡略化
• 開発・テスト・品質管理を統合的に実行

3 ツール併用の実例

状況に応じて、3 つのツールを組み合わせて使うこともできます。

pyenv + uv の組み合わせ

pyenv でバージョン管理し、uv で高速にパッケージをインストールする方法です。

bashCopy code# pyenv で Python 3.11.6 を使用
cd ~/projects/my-app
pyenv local 3.11.6

# uv で仮想環境を作成
uv venv

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

# uv で依存関係を高速インストール
uv pip install -r requirements.txt

この組み合わせは、既存のプロジェクトに uv を導入する際に有効です。pyenv による Python バージョン管理はそのままに、パッケージインストールだけを高速化できます。

Rye と pyenv の共存

Rye は内部で Python を管理しますが、既に pyenv を使っている環境でも共存可能です。

bashCopy code# pyenv でグローバル Python を設定（システム用）
pyenv global 3.11.6

# Rye プロジェクトでは独自の Python を使用
cd ~/projects/rye-project
rye pin 3.12

# Rye が自動的に Python 3.12 をインストール・管理
rye sync

Rye プロジェクト外では pyenv の設定が有効で、Rye プロジェクト内では Rye が管理する Python が使われます。両者は干渉しないため、安心して併用できますよ。

まとめ

macOS で Python 環境を快適に構築するには、pyenv、uv、Rye の 3 つのツールを理解し、適切に使い分けることが重要です。

pyenv は Python バージョン管理の定番ツールで、複数バージョンの切り替えが簡単に行えます。既存プロジェクトに導入しやすく、他のツールとの併用も可能です。

uv は Rust 製の超高速パッケージマネージャーで、pip の代替として使えます。大規模プロジェクトや CI/CD 環境で、インストール時間を大幅に短縮できるのが魅力ですね。

Rye はプロジェクト全体を統合管理できるオールインワンツールです。Python のインストールからパッケージ管理、スクリプト実行まで、すべてを一元化できます。

これらのツールを使いこなすことで、環境構築のストレスから解放され、本来の開発に集中できる環境が手に入ります。ぜひ、ご自身のプロジェクトに合ったツールを選んで、快適な Python ライフを実現してくださいね。

#	ツール	主な強み	推奨する人
1	pyenv	Python バージョン管理	複数プロジェクトで異なるバージョンを使う人
2	uv	超高速インストール	大規模プロジェクトや CI/CD を重視する人
3	Rye	統合プロジェクト管理	すべてを一つのツールで管理したい人

関連リンク

• pyenv 公式リポジトリ
• uv 公式ドキュメント
• Rye 公式サイト
• Homebrew 公式サイト
• Python 公式サイト
• FastAPI 公式ドキュメント
• pytest 公式ドキュメント