Voltaがメンテナンス終了したのでアンインストールと移行先を整理した

Voltaのメンテナンス終了

2025年11月、Node.jsバージョン管理ツールVoltaのメンテナンス終了が正式にアナウンスされた。

GitHub Issueの#2080で、メンテナーが以下の趣旨を表明している。

Voltaのメンテナーは現在miseを使っている
今動いているものはそのまま使えるが、新しいOSやエコシステムの変更による不具合は修正されない
新機能の開発も行われない

急いで移行する必要はないが、放置するとOSアップデートやNode.jsのメジャーバージョン更新でいつか壊れる。特にAIコーディングツールとの相性問題を抱えている場合は、早めに対処したほうがいい。

VoltaとAIツールのPATH競合問題

Voltaを使っていて地味に厄介だったのが、Claude CodeやCodexなどのグローバルインストールしたツールとの競合。

shimの仕組みが裏目に出る

Voltaは~/.volta/binにshim（中継用の実行ファイル）を置いて、nodeやnpmコマンドを横取りする。プロジェクトごとにバージョンを切り替えるための仕組みだが、これがグローバルにインストールしたツールと衝突する。

# Voltaが設定するPATH（簡略化）
~/.volta/bin → shimがここにある
  ├── node → volta-shim（実体はVoltaが管理するNode.jsに転送）
  ├── npm → volta-shim
  └── npx → volta-shim

具体的に何が起きるか

flowchart TD
    A["npm install -g claude-code"] --> B["Voltaのshim経由でインストール"]
    B --> C["~/.volta/tools/image/node/20.17.0/ 配下に配置"]
    C --> D["Volta管理下のNode 20.17.0に固定される"]
    D --> E["Node.jsを更新しても<br/>Claude Codeは古いNodeで動く"]
    E --> F["アップデートが効かない<br/>バージョン不整合が発生"]

claude-code#2789で報告されている実例:

volta pin node@20.18.2でプロジェクトにNode 20.18.2を指定
Claude Code内でnode --versionを実行するとNode 20.17.0が返る
VoltaがPATHの先頭に~/.volta/tools/image/node/20.17.0/binを挿入するため、shimを通さず直接古いバージョンが実行される

「抜いて入れ直し」が必要になるパターン

Claude Codeをアップデートしたはずなのにバージョンが変わらない
which claudeすると~/.volta/配下を指している
Voltaのキャッシュに古いバージョンが残っている
npm uninstall -g @anthropic-ai/claude-codeしてから再インストール、でようやく更新される

CodexやVercel CLIなど、グローバルインストールするツール全般で同じ問題が起きうる。ツールを更新するたびにこの手順を踏むのは現実的ではない。

Voltaの完全アンインストール

移行先を入れる前に、まずVoltaを完全に消す。中途半端に残るとPATHが二重になって余計に混乱する。

手順

1. シェル設定からVoltaのPATH設定を削除

~/.zshrc（または~/.bashrc）を開いて、以下の行を削除する。

export VOLTA_HOME="$HOME/.volta"
export PATH="$VOLTA_HOME/bin:$PATH"

2. Voltaディレクトリを削除

rm -rf ~/.volta

これでshim、キャッシュ、Volta管理下のNode.js・npm・パッケージがすべて消える。

3. package.jsonからVolta設定を削除（該当するプロジェクトがある場合）

// この部分を削除
{
  "volta": {
    "node": "20.18.2",
    "yarn": "1.22.22"
  }
}

4. 新しいターミナルを開いて確認

which node
# Voltaのパスが表示されなければOK

node --version
# システムのNode.jsバージョンが表示される
# 何も出なければNode.js自体が未インストール → 移行先で入れる

シェルはコマンドの場所をキャッシュしているので、必ず新しいターミナルを開くこと。hash -rでもキャッシュクリアできる。

移行先の比較

Voltaの代替として現実的な選択肢を比較する。

	fnm	mise	nvm	Homebrew（バージョン管理なし）
言語	Rust	Rust	シェルスクリプト	—
速度	速い	速い	遅い（シェル起動に影響）	—
Node.js以外	不可	Python, Ruby, Go等も管理可	不可	—
自動切替	`.node-version`, `.nvmrc`	`.mise.toml`, `.node-version`	`.nvmrc`（要設定）	なし
shimの有無	なし（PATHを直接切替）	なし（PATHを直接切替）	なし（PATHを直接切替）	—
グローバルツールとの競合	起きにくい	起きにくい	起きにくい	起きない

Voltaで問題だったshimによるPATH競合は、fnm・mise・nvmのいずれも発生しにくい。これらのツールはshimではなくPATH自体を書き換える方式を採用している。

fnm（Node.js専用で最もシンプル）

# macOS（Homebrew）
brew install fnm

# ~/.zshrcに追加
eval "$(fnm env --use-on-cd)"

# Node.jsのインストールと使用
fnm install 22
fnm use 22
fnm default 22

# プロジェクトにバージョンを固定
node --version > .node-version

Voltaからの移行で一番ギャップが少ない。Node.jsだけ管理できればいいならこれで十分。--use-on-cdオプションで.node-versionや.nvmrcを検知して自動切替してくれる。

mise（多言語対応のオールインワン）

# macOS（Homebrew）
brew install mise

# ~/.zshrcに追加
eval "$(mise activate zsh)"

# Node.jsのインストール
mise use --global node@22

# プロジェクトにバージョンを固定
mise use node@22
# → .mise.tomlが生成される

Voltaメンテナーの推奨。読み方は「ミーズ」（フランス語の”mise en place”から）。Node.jsだけでなくPython、Ruby、Go、Javaなども一元管理できる。環境変数の管理やタスクランナー機能もある。

多言語を扱うなら便利だが、Node.jsしか使わないならオーバースペック。

nvm（定番だが遅い）

# macOSの場合
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

歴史が長くドキュメントも豊富だが、シェルスクリプト実装のため起動が遅い。fnmやmiseと比較して20〜40倍遅いという計測がある。ターミナルを頻繁に開く人には体感で気になるレベル。

Homebrewだけで済ませる

brew install node

バージョン管理が不要なら最もシンプル。個人プロジェクトで最新のLTSだけ使っていれば十分、という場合はこれでいい。

移行後のグローバルツール再インストール

Voltaを消すとVolta管理下にあったグローバルツールもすべて消える。移行先でNode.jsを入れた後、必要なツールを入れ直す。

# 移行先でNode.jsをインストールした後
npm install -g @anthropic-ai/claude-code
npm install -g vercel

# 確認
which claude
# ~/.volta/ 配下でないことを確認
claude --version

Volta時代に発生していた「アップデートしたのに反映されない」問題は、shim経由でなくなるため解消する。

Voltaは良いツールだったが、メンテナンスされないソフトウェアはいずれ壊れる。Claude CodeのPATH競合で実害が出ているなら、後回しにせず移行してしまったほうが精神衛生上いい。Node.js専用ならfnm、多言語管理もしたいならmise。どちらもbrewで入る。