複数のNode.jsプロジェクトを並行して開発していると、プロジェクトAはNode.js 20系、プロジェクトBは22系——といったバージョンの使い分けが求められます。nodenvはディレクトリ単位でNode.jsのバージョンを自動切り替えできるツールで、Rubyのrbenvと同じ設計思想を持っています。
nodenvの特徴と仕組み
nodenvはシェルのPATHにshimディレクトリを差し込み、nodeやnpmの呼び出しを横取りして適切なバージョンへ振り分けます。具体的な動作は次のとおりです。
- カレントディレクトリの
.node-versionファイルを探す - 見つからなければ親ディレクトリを順に遡る
- いずれにもなければ
~/.nodenv/version（global設定）を参照する
この仕組みにより、cdでプロジェクトに入るだけでNode.jsバージョンが自動で切り替わります。.node-versionファイルをGitリポジトリに含めておけば、チームメンバー全員が同じバージョンで開発できます。
Node.jsバージョン管理ツールの比較
nodenvの他にもNode.jsバージョン管理ツールは複数存在します。プロジェクトの要件に合ったものを選ぶことが重要です。
| 項目 | nodenv | nvm | fnm | Volta |
|---|---|---|---|---|
| 実装言語 | シェルスクリプト | シェルスクリプト | Rust | Rust |
| バージョン切り替え速度 | 高速（shimベース） | 遅め（200ms以上） | 非常に高速 | 非常に高速 |
| Windows対応 | 非対応 | 非対応（WSL経由のみ） | 対応 | 対応 |
| 設定ファイル | .node-version | .nvmrc | .node-version / .nvmrc | package.json |
| npm/yarnのバージョン管理 | 不可 | 不可 | 不可 | 可能 |
| 設計の由来 | rbenv | 独自 | 独自 | 独自 |
| GitHub Stars（参考） | 約2.4k | 約92k | 約24k | 約13k |
nodenvはシンプルで軽量な設計が強みです。rbenvに慣れたRuby開発者には特に馴染みやすい操作体系になっています。一方、Windows環境での開発が必要な場合はfnmが適しています。なお、Voltaは2025年11月にメンテナンス終了が宣言されており、開発チームは後継としてmiseへの移行を推奨しています（出典: GitHub Issue #2080）。
macOSへのnodenvインストール手順
macOSでは2つの導入方法があります。
Homebrewで導入する
Homebrewがインストール済みであれば、以下のコマンドだけで完了します。
brew install nodenv
このコマンドはnodenv本体に加え、Node.jsのビルドに必要なnode-buildプラグインも自動で導入されます。
インストール後、バージョンを確認します。
nodenv -v
# nodenv 1.6.2 など
git cloneで導入する
Homebrewを使わない場合は、GitHubリポジトリから直接クローンします。
git clone https://github.com/nodenv/nodenv.git ~/.nodenv
続いてnode-buildプラグインを追加します。この時点ではまだPATHが通っていないため、パスを直接指定します。
mkdir -p ~/.nodenv/plugins
git clone https://github.com/nodenv/node-build.git ~/.nodenv/plugins/node-build
node-buildプラグインがないとnodenv installコマンドが使えないため、必ずセットで導入してください。
Ubuntu / WSL2へのnodenvインストール手順
UbuntuやWSL2環境ではgit cloneによるセットアップが基本です。
# 必要なパッケージの導入
sudo apt update
sudo apt install -y git curl build-essential
# nodenv本体のクローン
git clone https://github.com/nodenv/nodenv.git ~/.nodenv
# （任意）高速化のためbash拡張をコンパイル
cd ~/.nodenv && src/configure && make -C src
cd ~
# node-buildプラグインの追加
mkdir -p ~/.nodenv/plugins
git clone https://github.com/nodenv/node-build.git ~/.nodenv/plugins/node-build
build-essentialパッケージはNode.jsをソースからビルドする際に必要です。これがないとインストール時にエラーになるケースがあります。
シェル設定の追加（bash / zsh / fish）
nodenvの導入後、シェルの初期化ファイルにPATHとinit設定を追加します。
bash（Ubuntu / WSL2 のデフォルト）
~/.bashrcに以下を追記します。
export PATH="$HOME/.nodenv/bin:$PATH"
eval "$(nodenv init - bash)"
zsh（macOSのデフォルト）
~/.zshrcに以下を追記します。
export PATH="$HOME/.nodenv/bin:$PATH"
eval "$(nodenv init - zsh)"
fish
~/.config/fish/config.fishに以下を追記します。
set -gx PATH $HOME/.nodenv/bin $PATH
nodenv init - fish | source
設定を追記したら、シェルを再起動するかsourceコマンドで反映させます。
# bash / zshの場合
source ~/.bashrc # または source ~/.zshrc
正しく設定できたかどうかはnodenv-doctorスクリプトで診断できます。
curl -fsSL https://github.com/nodenv/nodenv-installer/raw/HEAD/bin/nodenv-doctor | bash
このスクリプトはPATH設定・shim・プラグインの状態をまとめてチェックし、問題があれば具体的な修正手順を表示します。
nodenv installでNode.jsを導入する
インストール可能なバージョン一覧を確認する
nodenv install -l（--listの省略形）でインストール可能なバージョン一覧を確認できます。
nodenv install -l
出力例：
20.18.1
20.18.2
20.18.3
22.11.0
22.12.0
22.13.0
22.13.1
22.14.0
...
24.12.0
24.13.0
24.13.1
全バージョン（開発版やRCを含む）を表示したい場合は--list-allオプションを使います。
nodenv install --list-all
Node.jsをインストールする
バージョンを指定してインストールします。2026年2月時点のLTSバージョンを例にすると次のようになります。
# Node.js 22系（LTS: Jod）をインストール
nodenv install 22.22.0
# Node.js 24系（LTS: Krypton）をインストール
nodenv install 24.13.1
インストールが完了したらnodenv rehashを実行します。これにより、新しくインストールされたNode.jsの実行ファイルへのshimが生成されます。
nodenv rehash
Homebrew経由でnodenvを導入した場合、
nodenv rehashは自動実行されることが多いですが、手動で実行しても問題ありません。
インストール済みのバージョンを一覧表示するにはnodenv versionsを使います。
nodenv versions
出力例：
22.22.0
* 24.13.1 (set by /home/user/.nodenv/version)
*が付いているバージョンが現在アクティブなものです。
nodenvでバージョンを切り替える
nodenvには3段階のバージョン指定方法があり、優先順位はshell > local > globalです。
global — マシン全体のデフォルト
nodenv global 22.22.0
~/.nodenv/versionファイルにバージョン番号が書き込まれます。どのディレクトリからでも、他の指定がなければこのバージョンが使われます。
local — プロジェクト単位の指定
cd /path/to/project
nodenv local 24.13.1
カレントディレクトリに.node-versionファイルが作成されます。このファイルをGitに含めることで、チーム全体のNode.jsバージョンを統一できます。
# .node-versionの中身
cat .node-version
# 24.13.1
shell — 現在のシェルセッション限定
nodenv shell 20.18.3
環境変数NODENV_VERSIONにバージョンがセットされ、そのターミナルセッション内でのみ有効です。一時的に別バージョンで動作確認したいときに便利です。解除するには次のコマンドを実行します。
nodenv shell --unset
nodenvのアップデートとバージョンリストの更新
Homebrew経由のアップデート
brew upgrade nodenv node-build
git clone導入の場合
cd ~/.nodenv
git pull
cd "$(nodenv root)"/plugins/node-build
git pull
nodenv install -lで新しいNode.jsバージョンが表示されない場合、ほとんどのケースでnode-buildプラグインが古いことが原因です。node-buildを更新すれば最新のバージョン一覧が反映されます。
nodenv-updateプラグインを導入しておくと、nodenv本体とすべてのプラグインをワンコマンドで更新できます。
# nodenv-updateプラグインの導入
git clone https://github.com/nodenv/nodenv-update.git "$(nodenv root)"/plugins/nodenv-update
# 一括アップデートの実行
nodenv update
Node.jsとnodenvのアンインストール
特定バージョンのNode.jsを削除する
nodenv uninstall 20.18.3
確認プロンプトが表示されるのでyを入力します。-fオプションを付けるとプロンプトをスキップできます。
nodenv自体の削除
Homebrew経由で導入した場合：
brew uninstall nodenv node-build
git clone経由の場合：
rm -rf "$(nodenv root)"
いずれの場合も、シェル設定ファイル（~/.bashrc、~/.zshrc等）からnodenv関連の記述を削除してください。
よくあるトラブルと対処法
install -l に目的のバージョンが表示されない
node-buildプラグインのバージョン定義ファイルが古い可能性があります。
# Homebrew経由の場合
brew upgrade node-build
# git clone経由の場合
cd "$(nodenv root)"/plugins/node-build && git pull
更新後、再度nodenv install -lを実行して目的のバージョンが表示されるか確認してください。
nodenv: command not found が表示される
PATHの設定が正しく読み込まれていない状態です。以下を確認してください。
~/.nodenv/binがPATHに含まれているか
echo $PATH | tr ':' '\n' | grep nodenv
- シェルの初期化ファイルに設定が正しく記述されているか
- 設定後にシェルを再起動（または
source）したか
nodeコマンドが見つからない
nodenv installでNode.jsをインストールした直後にnodeコマンドが見つからない場合、shimの再生成が必要です。
nodenv rehash
それでも解決しない場合は、nodenv globalまたはnodenv localでバージョンを明示的に指定してみてください。
nodenv global 22.22.0
node -v
# v22.22.0
nodenv init で「~/.nodenv/shims がPATHにない」と警告される
nodenv initが出力するスクリプトをシェル設定ファイルの末尾近くに配置しているか確認してください。他のツール（例: anyenv）がPATHを上書きしている場合、nodenvのshimディレクトリが外れてしまうことがあります。
anyenv経由でnodenvを管理する
anyenvはnodenvだけでなく、rbenv・pyenv・goenvなど複数の**env系ツールを一元管理するラッパーです。Ruby・Python・Goなど複数言語のバージョン管理が必要な環境では、anyenvを使うとインストールや更新の手間が減ります。
# anyenvのインストール
git clone https://github.com/anyenv/anyenv ~/.anyenv
echo 'export PATH="$HOME/.anyenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(anyenv init -)"' >> ~/.bashrc
source ~/.bashrc
# anyenv経由でnodenvをインストール
anyenv install nodenv
exec $SHELL -l
anyenv経由の場合、nodenvは~/.anyenv/envs/nodenv/配下に配置されます。それ以降の使い方（nodenv install、nodenv global等）は直接インストールした場合と同じです。
ただし、nodenv単体で十分な場合はanyenvを挟む必要はありません。管理対象のツールが増えるほどanyenvの利便性が高まるため、利用状況に応じて判断してください。
まとめ
nodenvはshimベースの軽量なNode.jsバージョン管理ツールです。.node-versionファイルによるプロジェクト単位の自動切り替えが最大の利点で、チーム開発でのバージョン統一に効果的です。
主要なポイントを整理します。
- macOSは
brew install nodenv、Ubuntu / WSL2はgit cloneで導入する - Node.jsのインストールには
nodenv install <バージョン>を使う global/local/shellの3段階でバージョンを制御する- バージョン一覧が古い場合はnode-buildプラグインを更新する
- Windows環境ではnodenvは動作しないため、fnmやmiseを検討する
nodenvの公式リポジトリはGitHub（nodenv/nodenv）で公開されています。コマンドの詳細やプラグイン一覧はこちらで確認できます。