Volta is end-of-life, so I organized the uninstall steps and migration options

Volta maintenance has ended

In November 2025, end-of-maintenance for the Node.js version manager Volta was officially announced.

In GitHub Issue #2080, the maintainer said, in substance:

• The maintainer of Volta is currently using mise
• What already works will continue to work, but bugs caused by new OS releases or ecosystem changes will no longer be fixed
• No new features will be developed

There is no need to migrate in a panic, but if you leave it in place, it will eventually break on an OS update or a future major Node.js release. If you already have compatibility issues with AI coding tools, it makes sense to deal with it sooner rather than later.

Volta’s PATH conflicts with AI tools

The annoying part of using Volta was conflicts with globally installed tools such as Claude Code and Codex.

The shim mechanism backfires

Volta places shims (intermediary executables) under ~/.volta/bin and intercepts commands such as node and npm. That is how it switches versions per project, but it also collides with globally installed tools.

# PATH configured by Volta (simplified)
~/.volta/bin -> this is where the shims live
  ├── node -> volta-shim (forwards to the Node.js version managed by Volta)
  ├── npm -> volta-shim
  └── npx -> volta-shim

What actually happens

flowchart TD
    A["npm install -g claude-code"] --> B["Installed through Volta's shim"]
    B --> C["Placed under ~/.volta/tools/image/node/20.17.0/"]
    C --> D["Pinned to the Node 20.17.0 managed by Volta"]
    D --> E["Even if Node.js is updated,<br/>Claude Code still runs on the old Node"]
    E --> F["Updates do not apply correctly,<br/>causing version mismatches"]

A real example reported in claude-code#2789:

• volta pin node@20.18.2 is used to pin Node 20.18.2 in a project
• Running node --version inside Claude Code returns Node 20.17.0
• Because Volta inserts ~/.volta/tools/image/node/20.17.0/bin at the front of PATH, the old version runs directly instead of going through the shim

The pattern where you have to “remove and reinstall”

1. You think you updated Claude Code, but the version does not change
2. which claude points into ~/.volta/
3. An older version still exists in Volta’s cache
4. Only after npm uninstall -g @anthropic-ai/claude-code and reinstalling does the update finally apply

The same problem can happen with any globally installed tool, including Codex and Vercel CLI. Having to repeat this every time you update a tool is not realistic.

Completely uninstalling Volta

Before installing the replacement, remove Volta completely. If it remains half-installed, PATH ends up duplicated and things get more confusing.

Steps

1. Remove Volta’s PATH settings from your shell config

Open ~/.zshrc (or ~/.bashrc) and delete these lines.

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

2. Delete the Volta directory

rm -rf ~/.volta

This removes the shims, cache, and every Node.js, npm, and package managed under Volta.

3. Remove Volta settings from package.json if any projects still have them

// Delete this section
{
  "volta": {
    "node": "20.18.2",
    "yarn": "1.22.22"
  }
}

4. Open a new terminal and verify

which node
# OK if it no longer shows a Volta path

node --version
# Should show the system Node.js version
# If nothing appears, Node.js itself is not installed -> install it with the new tool

Your shell caches command locations, so make sure to open a new terminal. hash -r can also clear the cache.

Comparing migration targets

Here is a practical comparison of the realistic replacements for Volta.

	fnm	mise	nvm	Homebrew (no version management)
Language	Rust	Rust	Shell script	-
Speed	Fast	Fast	Slow (affects shell startup)	-
Beyond Node.js	No	Can also manage Python, Ruby, Go, etc.	No	-
Auto switching	.node-version, .nvmrc	.mise.toml, .node-version	.nvmrc (requires setup)	None
Uses shims	No (switches PATH directly)	No (switches PATH directly)	No (switches PATH directly)	-
Global-tool conflicts	Unlikely	Unlikely	Unlikely	None

The shim-based PATH conflict that caused trouble in Volta is much less likely with fnm, mise, or nvm. These tools rewrite PATH directly instead of inserting shim executables.

fnm (the simplest if you only need Node.js)

# macOS (Homebrew)
brew install fnm

# Add to ~/.zshrc
eval "$(fnm env --use-on-cd)"

# Install and use Node.js
fnm install 22
fnm use 22
fnm default 22

# Pin a version for the project
node --version > .node-version

This is the smallest conceptual jump from Volta. If all you need is Node.js version management, it is enough. With --use-on-cd, it auto-switches when it detects .node-version or .nvmrc.

mise (all-in-one, multi-language)

# macOS (Homebrew)
brew install mise

# Add to ~/.zshrc
eval "$(mise activate zsh)"

# Install Node.js
mise use --global node@22

# Pin a version for the project
mise use node@22
# -> generates .mise.toml

This is the option recommended by Volta’s maintainer. It is pronounced “meez” (from the French phrase “mise en place”). It can manage not only Node.js but also Python, Ruby, Go, Java, and more. It also includes environment-variable management and a task runner.

That is useful if you work across multiple languages, but overkill if you only need Node.js.

nvm (classic, but slow)

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

It has been around for a long time and has plenty of documentation, but because it is implemented as shell scripts, startup is slow. Measurements often put it at 20-40x slower than fnm or mise. If you open terminals frequently, you will feel it.

Just use Homebrew

brew install node

If you do not need version management, this is the simplest route. If you only use the latest LTS in personal projects, this may be enough.

Reinstall global tools after migration

Removing Volta also removes every global tool under Volta management. After installing Node.js with the new tool, reinstall what you actually need.

# After installing Node.js with the new manager
npm install -g @anthropic-ai/claude-code
npm install -g vercel

# Verify
which claude
# Confirm it is no longer under ~/.volta/
claude --version

The old “I updated it but nothing changed” problem goes away once the tool no longer runs through Volta’s shim layer.

---

Volta was a good tool, but unmaintained software eventually breaks. If Claude Code’s PATH conflict is already causing real problems, it is better for your sanity to migrate now instead of postponing it. Use fnm if you only want Node.js; use mise if you want multi-language tool management. Both install cleanly with Homebrew.