Volta Cheat Sheet

Overview

Volta is a JavaScript tool version manager that provides fast, reliable version management for Node.js, npm, yarn, pnpm, and JavaScript CLI tools. Unlike NVM, Volta uses a shim-based approach with native binaries (written in Rust) for near-zero overhead switching, and pins tool versions per-project in package.json for seamless team-wide consistency.

Volta automatically switches Node.js versions when you enter a project directory, requires no shell hooks or .nvmrc files (though it supports them), and works identically across macOS, Linux, and Windows. It manages global tool installations per Node version and supports “platform-aware” toolchains where each project can specify its exact Node, npm, and yarn versions.

Installation

# macOS / Linux
curl https://get.volta.sh | bash

# macOS via Homebrew
brew install volta
volta setup

# Windows
# Download installer from https://volta.sh

# With custom installation directory
VOLTA_HOME=/custom/path curl https://get.volta.sh | bash

# Verify installation
volta --version

# Shell integration is automatic via ~/.bashrc or ~/.zshrc
# export VOLTA_HOME="$HOME/.volta"
# export PATH="$VOLTA_HOME/bin:$PATH"

Core Commands

Command	Description
volta install <tool>	Install a tool globally
volta pin <tool>	Pin a tool version in package.json
volta uninstall <tool>	Uninstall a globally installed tool
volta list	List installed tools and runtimes
volta list all	List all installed versions
volta fetch <tool>	Download a tool without installing
volta run <tool>	Run a tool with a specific version
volta which <tool>	Show path to a tool binary
volta setup	Configure shell integration
volta completions <shell>	Generate shell completions

Installing Node.js

# Install latest LTS
volta install node

# Install specific version
volta install node@20.11.0
volta install node@18

# Install latest of a major version
volta install node@22

# Install latest (not just LTS)
volta install node@latest

# Check installed version
volta list node
node --version

# Install multiple versions
volta install node@18
volta install node@20
volta install node@22

Installing Package Managers

# Install npm (specific version)
volta install npm@10

# Install yarn
volta install yarn
volta install yarn@4

# Install pnpm
volta install pnpm
volta install pnpm@9

# Check versions
volta list
npm --version
yarn --version
pnpm --version

Pinning Versions (Per-Project)

# Pin Node.js version for project
cd /path/to/project
volta pin node@20.11.0

# Pin npm version
volta pin npm@10

# Pin yarn version
volta pin yarn@4.1.0

# Pin pnpm version
volta pin pnpm@9.0.0

# This adds to package.json:
# "volta": {
#   "node": "20.11.0",
#   "npm": "10.2.4",
#   "yarn": "4.1.0"
# }

{
  "name": "my-project",
  "volta": {
    "node": "20.11.0",
    "npm": "10.2.4"
  }
}

Global Tool Management

# Install global CLI tools
volta install typescript
volta install eslint
volta install prettier
volta install @angular/cli
volta install create-react-app

# Tools are isolated per Node version
volta install node@20
volta install typescript  # Installed for Node 20

# List installed tools
volta list all

# Uninstall a global tool
volta uninstall typescript

# Check which binary is used
volta which tsc
volta which node
volta which npm

Version Switching

# Volta switches automatically based on package.json
cd project-a  # Uses Node 20 (from package.json volta config)
node --version  # v20.11.0

cd project-b  # Uses Node 18 (from package.json volta config)
node --version  # v18.19.0

cd ~  # Uses default version
node --version  # Whatever was installed with `volta install node`

# Run with a specific version temporarily
volta run --node 22 -- node -e "console.log(process.version)"
volta run --node 18 --npm 9 -- npm install

# Use a bundled npm version
volta run --bundled-npm -- npm --version

Listing Installed Versions

# List default tools
volta list

# List all installed versions
volta list all

# List specific tool versions
volta list node
volta list yarn
volta list npm

# Show current active versions
volta list --current

Fetching Without Installing

# Download Node.js for later use (useful for CI)
volta fetch node@20.11.0
volta fetch yarn@4.1.0

# Fetch and then install
volta fetch node@22
volta install node@22

Advanced Usage

CI/CD Integration

# GitHub Actions
name: CI
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: volta-cli/action@v4
      - run: node --version  # Uses version from package.json
      - run: npm ci
      - run: npm test

# CI script - Volta auto-installs pinned versions
curl https://get.volta.sh | bash
export VOLTA_HOME="$HOME/.volta"
export PATH="$VOLTA_HOME/bin:$PATH"
cd /project
npm ci    # Node version from package.json is used automatically
npm test

Shell Completions

# Bash
volta completions bash > /etc/bash_completion.d/volta

# Zsh
volta completions zsh > ~/.zfunc/_volta

# Fish
volta completions fish > ~/.config/fish/completions/volta.fish

Migrating from NVM

# 1. Install Volta
curl https://get.volta.sh | bash

# 2. Install your default Node version
volta install node@20

# 3. Pin versions in each project
cd my-project
volta pin node@20

# 4. Replace .nvmrc with package.json volta config
# Remove .nvmrc files
# The volta pin command handles everything

# 5. Remove NVM from shell profile
# Remove NVM-related lines from ~/.bashrc or ~/.zshrc

Configuration

# Environment variables
export VOLTA_HOME="$HOME/.volta"         # Volta installation directory
export VOLTA_FEATURE_PNPM=1             # Enable pnpm support
export PATH="$VOLTA_HOME/bin:$PATH"     # Add Volta to PATH

# Volta stores data in:
# ~/.volta/tools/node/        - Node.js installations
# ~/.volta/tools/npm/         - npm installations
# ~/.volta/tools/yarn/        - Yarn installations
# ~/.volta/tools/image/       - Global tool installations
# ~/.volta/bin/               - Shim binaries

Troubleshooting

Issue	Solution
volta: command not found	Run volta setup; source your shell profile
Wrong Node version	Check package.json for volta field; run volta list --current
Global tool not found	Reinstall with volta install <tool>; check volta which <tool>
pnpm not working	Set export VOLTA_FEATURE_PNPM=1 before using pnpm
Slow first run	Volta downloads on first use; subsequent runs are instant
Conflicts with NVM	Remove NVM from shell profile; only use one version manager
Permission errors	Volta installs to home directory; never use sudo
CI not picking up version	Ensure Volta is installed and package.json has volta field