MacでPython環境を構築する完全ガイド：pyenv・Docker・VS Code連携のベストプラクティス

はじめに

Mac上でのPython環境構築は、開発者にとって避けて通れない重要な工程です。本記事では、既存の「MacでPython環境を構築する方法とDockerを使った効率的な開発環境の作り方」記事をベースに、より実践的で包括的な改善案をご紹介します。

macOS標準Pythonの問題点と注意事項

macOS標準のPythonが2系であることを明示

多くのmacOSにはPython 2.xが同梱されていますが、Python 2は既にサポートが終了しています。GeeksforGeeksのガイドでは、「macOSにプリインストールされているPythonは古い2.x系の場合が多く、最新機能を利用するにはPython 3.xをインストールする必要がある」と指摘されています。

Homebrewのインストールに関する注意喚起

HomebrewはmacOSの定番パッケージマネージャーですが、以下の点に注意が必要です：

インストール時のみsudoを利用し、その後は管理者権限を用いない
/opt/homebrewへのPATH設定が必要
インストール後にPATHを設定すると、sudoが不要になる

Pythonバージョン管理ツール（pyenv）の導入

pyenvの利点

従来の記事では仮想環境（venv）のみを紹介していますが、複数バージョンの切り替えが必要な場合はpyenvの利用を強く推奨します。Real Pythonはpyenvを「複数のPythonバージョンを管理できる優れたツール」と評価しており、システムPythonやパッケージマネージャーによるグローバルインストールが引き起こす依存関係の衝突を避けられます。

pyenvのインストール手順

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

# シェル設定ファイルに初期化コマンドを追加
echo 'export PATH="$HOME/.pyenv/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
source ~/.zshrc

# 最新のPython 3をインストール
pyenv install 3.12.0
pyenv global 3.12.0

Dockerのベストプラクティス

適切なベースイメージの選定

従来の記事ではpython:3.12-slimを例示していますが、用途に応じて以下を選択することを推奨します：

python:3.x-slim：一般的な開発用途（推奨）
python:3.x-alpine：軽量だがビルドライブラリが不足することがある
python:3.x-buster：フル機能が必要な場合

Apple Siliconへの対応

重要：ARM64ベースのApple Siliconでは、x86ベースのイメージが正常に動作しない場合があります。公式のpython:3.x-slim-busterなどARM対応イメージを利用してください。

# Apple Silicon対応Dockerfile例
FROM python:3.12-slim

# 作業ディレクトリの設定
WORKDIR /app

# requirements.txtをコピー（キャッシュ効率化）
COPY requirements.txt .

# パッケージインストール（キャッシュなし）
RUN pip install --no-cache-dir -r requirements.txt

# アプリケーションコードをコピー
COPY . .

# アプリケーション実行
CMD ["python", "app.py"]

マルチステージビルドとキャッシュ活用

Dockerイメージのサイズを抑えるためのテクニック：

pip install --no-cache-dirの利用
.dockerignoreファイルの設定
マルチステージビルドによる最適化

VS Code Dev Containersの活用方法

Dev Containers拡張機能のメリット

Visual Studio Codeの「Dev Containers」拡張は、Dockerコンテナ内でフル機能の開発環境を利用できる優れた機能です。これにより：

環境の再現性が大幅に向上
プロジェクトごとに独立した開発環境を簡単に切り替え可能
チーム全体で統一された開発環境を共有

基本的な設定手順

VS CodeにDev Containers拡張機能をインストール
Docker Desktopを導入
プロジェクトルートに.devcontainer/devcontainer.jsonを作成
VS Code上で「Reopen in Container」を実行

{
  "name": "Python 3",
  "image": "python:3.12-slim",
  "customizations": {
    "vscode": {
      "extensions": [
        "ms-python.python",
        "ms-python.pylint"
      ]
    }
  },
  "postCreateCommand": "pip install -r requirements.txt"
}