Get Started

znvm — Zero-overhead Node Version Manager

A blazingly fast, zero-config Node.js version manager built with Zig. It solves the nvm-slow problem with < 5ms startup time.

Installation

Quick Install (Recommended)

curl -fsSL https://znvm.dev/install.sh | bash

Then restart your terminal or run:

source ~/.zshrc  # or ~/.bashrc

What the installer does

1. Detects your platform (macOS/Linux) and architecture (x64/arm64)
2. Downloads the latest znvm binary to ~/.znvm/bin/
3. Adds znvm to your PATH in shell profile
4. Sets up the shell wrapper for use command and auto-switching

Shell Setup

If the automatic setup didn't work, add this to your shell profile (~/.zshrc, ~/.bashrc, etc.):

eval "$(znvm env)"

This command:

• Adds znvm to your PATH
• Sets up the shell wrapper for the use command
• Enables auto-switching when you cd into directories with .nvmrc

Usage

Install Node.js

znvm supports SemVer patterns. Use 22 to get the latest v22.x.x:

znvm install 22           # Latest v22.x.x
znvm install 20.11.0      # Specific version
znvm install v18.20.0     # With v prefix

Switch Versions

znvm use 20               # Switch to Node 20
znvm use                  # Auto-detect from .nvmrc

List Installed Versions

znvm ls
# or
znvm list

Output shows:

• [*] - Currently active version
• [->] - Default version

Set Default Version

znvm default 20           # Set v20 as default
znvm default              # Show current default

The default version is used when:

• No .nvmrc file exists in current directory
• The .nvmrc version is not installed

Uninstall a Version

znvm uninstall 20
# or
znvm rm 20

Auto Switching with .nvmrc

znvm automatically switches Node versions when you cd into a directory with .nvmrc:

echo "20" > .nvmrc        # Create .nvmrc
cd /my-project            # Auto-switches to Node 20

Note: Auto-switching is enabled by default when you use eval "$(znvm env)" in your shell profile.

Environment Variables

Variable	Description	Default
ZNVM_DIR	znvm installation directory	~/.znvm
NVM_NODEJS_ORG_MIRROR	Node.js download mirror	-

Mirror Configuration

For users in China, use a mirror to speed up downloads:

export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node

Global Package Isolation

Each Node.js version has isolated:

• Global npm packages (npm install -g)
• npm cache
• Corepack (pnpm/yarn)

This prevents version conflicts between different Node versions.

Commands Reference

Command	Description
znvm install <ver>	Install a Node.js version
znvm use [ver]	Switch to version (or use .nvmrc)
znvm ls	List installed versions
znvm default [ver]	Set/show default version
znvm uninstall <ver>	Remove a version
znvm version	Show znvm version
znvm env	Output shell configuration

Troubleshooting

Command not found

Make sure ~/.znvm/bin is in your PATH:

export PATH="$HOME/.znvm/bin:$PATH"

Version not found after install

Run znvm use <version> or restart your terminal.

Auto-switch not working

Ensure the shell wrapper is loaded in your profile:

eval "$(znvm env)"

If you want to disable auto-switch, remove or comment out the eval "$(znvm env)" line from your shell profile.

---

Related: Why we built znvm | GitHub