Volta: Pin a Node Toolchain with volta install

volta pin writes the Node/npm/yarn versions into package.json's "volta" key, and Volta's shims then transparently run that exact toolchain in any directory of the project.

Volta differs from nvm/fnm: instead of you switching versions, it installs shims that detect the pinned toolchain from package.json and run it automatically, with no per-shell activation.

What it does

Volta installs shims for node, npm, yarn, and pinned binaries onto PATH. When you run node, the shim reads the nearest package.json "volta" key and executes that version, downloading it on first use. volta pin records the version; volta install adds a global tool.

Common usage

bash

volta pin node@20.11.1        # writes "volta": { "node": "20.11.1" } to package.json
volta pin npm@10
volta install pnpm            # global tool, shimmed
node -v                       # runs the pinned version automatically
volta list                    # show installed toolchains

Options

Command / flag	What it does
volta pin <tool>@<v>	Record a toolchain version in package.json
volta install <tool>	Install a global tool as a Volta shim
volta run --node <v> <cmd>	Run one command under a specific Node
volta list	List installed/pinned tools
VOLTA_HOME	Override the install/cache directory
VOLTA_FEATURE_PNPM=1	Enable Volta-managed pnpm shimming

In CI

Install Volta and ensure $VOLTA_HOME/bin is on PATH; after that no activation is needed because the shims read package.json. Cache $VOLTA_HOME so pinned toolchains are not re-downloaded each run. The pin lives in version control, so every runner gets the identical Node.

Common errors in CI

"command not found: volta" means $VOLTA_HOME/bin is not on PATH. "Volta error: Could not locate executable" can mean the package.json "volta" key references a version that failed to download (network) - check the fetch step. If node -v ignores your pin, you are running outside the project tree where package.json with the volta key lives.