macOSでPythonとNode.jsの複数バージョンを管理する完全ガイド

はじめに

開発プロジェクトでは、異なるバージョンのPythonやNode.jsが必要になることがよくあります。この記事では、macOSで複数のバージョンを効率的に管理する方法を、実際の環境構築手順とともに解説します。

必要なツールの概要

バージョン管理ツール

• pyenv: Pythonのバージョン管理
• nvm: Node.jsのバージョン管理
• Poetry: Python依存関係管理（仮想環境も提供）

インストール方法の選択

• Homebrew: macOSのパッケージマネージャー（推奨）
• 各ツールの公式インストールスクリプト

環境構築手順

1. Homebrewの確認

brew --version
# Homebrew 4.5.2

2. Poetryのインストール

# Homebrewでインストール
brew install poetry

# バージョン確認
poetry --version
# Poetry (version 2.1.3)

3. nvmのインストール

# 公式インストールスクリプトを使用
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# シェル設定の再読み込み（.zshrcに自動追加される）
source ~/.zshrc

4. Node.jsのインストール

# Node.js v18をインストール
nvm install 18

# 使用するバージョンを指定
nvm use 18

# バージョン確認
node --version
# v18.20.8

5. pyenvのインストール

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

# .zshrcに設定を追加
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc

# 設定を反映
source ~/.zshrc

6. Pythonのインストール

# Python 3.10をインストール
pyenv install 3.10.15

# グローバルで使用するバージョンを設定
pyenv global 3.10.15

# バージョン確認
python --version
# Python 3.10.15

プロジェクトごとのバージョン管理

Node.js: .nvmrcファイルの活用

# プロジェクトルートに.nvmrcを作成
echo "18" > .nvmrc

# プロジェクトディレクトリに入ったら
nvm use  # .nvmrcを自動的に読み込む

自動切り替えの設定（zsh）

# ~/.zshrcに追加
autoload -U add-zsh-hook
load-nvmrc() {
  if [[ -f .nvmrc && -r .nvmrc ]]; then
    nvm use
  fi
}
add-zsh-hook chpwd load-nvmrc
load-nvmrc

Python: pyenvとPoetryの使い分け

pyenvでローカル設定

# プロジェクトディレクトリで実行
pyenv local 3.10.15
# .python-versionファイルが作成される

Poetryで仮想環境を管理

# プロジェクト内に仮想環境を作成する設定
poetry config virtualenvs.in-project true

# 依存関係をインストール
poetry install

# 仮想環境の有効化（どちらでもOK）
source .venv/bin/activate  # 従来の方法
poetry shell              # Poetry専用コマンド

Poetryの仮想環境について

なぜプロジェクトごとに仮想環境を作るのか？

1. 独立性: 他のプロジェクトと依存関係が混ざらない
2. 再現性: poetry.lockで完全に同じ環境を再現
3. 安全性: システムのPythonを汚染しない

使い方の比較

従来の方法

source .venv/bin/activate
python main.py
deactivate

Poetry方式

poetry run python main.py  # 一時的に実行
poetry shell              # 新しいシェルで仮想環境

PythonとNode.jsの違い

Python（venv/Poetry）

• プロジェクトごとにパッケージ環境を分離
• Python本体のバージョン + インストールされたパッケージ

Node.js（nvm）

• Node.js本体のバージョンを切り替え
• node_modulesは元々プロジェクトごとに独立

まとめ

macOSでの開発環境構築のポイント：

1. Homebrewで可能な限りインストール（管理が楽）
2. プロジェクトごとにバージョンを固定（.nvmrc、.python-version）
3. Poetryで依存関係を管理（poetry.lock）
4. 仮想環境は慣れた方法で使える（source .venv/bin/activate）

これらのツールを使いこなすことで、複数のプロジェクトを同時に開発する際も、バージョンの競合を避けて効率的に作業できます。

参考リンク

• pyenv GitHub
• nvm GitHub
• Poetry 公式ドキュメント