Per-project Node.js versions, scoped to your terminal session.
Pin a version to a project once. From then on, every terminal you open inside that project uses it — and nowhere else on the machine changes. Close the terminal and your own Node is back.
It replaces doing this by hand in every shell:
export PATH="/c/nodes/nodejs14:$PATH"
hash -r
Install
npm install -g @ubuligan/nodevm
nodevm setup # once per machine, per shell
Then open a new terminal.
nodevm itself needs Node 18.17.0 or newer. That is a genuine chicken-and-egg: a JavaScript CLI needs a modern Node to run, while existing to rescue you from old ones. If your only Node is older, nodevm tells you so and names the minimum — it does not fail with a cryptic engines error. Once installed, it manages any version, Node 14 included.
setup prints exactly what it changed and is fully reversible with nodevm setup --undo.
Use it
cd my-legacy-app
nodevm install 14 --pin # installs Node 14 and writes .nvmrc
cd .. # your own Node
cd my-legacy-app # Node 14, automatically
That is the whole workflow. No command to run per terminal, no PATH editing.
nodevm ls-remote # ~12 rows: newest of each LTS line + current
nodevm ls-remote --all # every published release
nodevm install # interactive picker
nodevm ls # what is installed here (never uses the network)
nodevm current # what is active, and why
nodevm which # path to the node that would run
nodevm use 20 # activate in THIS terminal only
nodevm use --unpin # remove this project's pin
nodevm uninstall 14
Already have Node folders?
Register them instead of downloading again. nodevm never modifies, moves, or deletes them.
nodevm link "C:\nodes\nodejs14"
nodevm link "C:\nodes\nodejs14" --remove # removes only the registration
How pinning works
The pin lives in .nvmrc — one line, committed to your repo. It is the same file nvm, fnm,
nodenv and Volta read, so a project you pin works for teammates using those tools, and a project
they pinned works here with no changes.
When .nvmrc is absent, nodevm also reads .node-version, then package.json engines.node
(treated as a range: the newest installed version that satisfies it wins). nodevm use --unpin
deletes only the .nvmrc nodevm wrote — never the other two, which it never created.
The innermost pin wins, so a package inside a monorepo can differ from its parent.
How it works
A child process cannot change its parent shell's PATH, so nodevm setup installs a small shell
hook. On every directory change the hook is pure shell: it walks up for the nearest pin file and
compares a path:mtime:size fingerprint. If nothing changed — the usual case — it spawns no process
at all. Only when the pin actually changes does it call nodevm, which prints the PATH change as
shell code for the hook to eval.
Nothing is written to disk when you switch. The active version lives in three environment variables in that one session, which is why closing the terminal needs no cleanup, and why two terminals in two differently pinned projects run different versions at the same time.
Deactivation removes exactly the directory that was added, by string match — never a pattern
strip. A PATH entry you set by hand survives untouched.
Safety
- Downloads come only from
https://nodejs.org/dist(or a mirror you set withNODEVM_MIRROR). - Every archive is checked against the official
SHASUMS256.txtbefore extraction. A mismatch installs nothing. - Extraction happens in a temp directory and is promoted with one atomic rename, so an interrupted
install can never leave a half-version that
lsreports as installed. - Everything lives under
~/.nodevm. No administrator rights, ever. Nothing outside that directory is touched except the one consentedsetupchange to your shell config. - Concurrent installs of the same version take a lock: the second waits, then succeeds. Locks left by a crashed process expire.
Not verified: GPG signatures on SHASUMS256.txt. Checksums are verified over HTTPS; signature
verification would need a crypto dependency and a key-distribution story. This is a deliberate,
documented gap, not an oversight.
Platform notes
Windows, macOS and Linux, on x64 and arm64. Git Bash, PowerShell, cmd.exe, bash, zsh and fish.
No native build for your machine? Some old versions publish none — Node 14 has no Apple Silicon
build, for instance. nodevm checks the release index before downloading and either offers the x64
build under Rosetta (--rosetta to pre-answer) or names the oldest version that does have a native
build. It never silently substitutes an emulated build, and never fails with a mid-download 404.
cmd.exe limitation. cmd.exe raises no directory-change event, so nodevm intercepts cd with a
doskey macro. Those macros do not expand inside batch files, so a cd in a .bat does not trigger
automatic switching. Interactive cd does. nodevm use <version> works everywhere, batch files
included. nodevm setup states this when you install it.
Uninstall
nodevm setup --undo
npm uninstall -g @ubuligan/nodevm
rm -rf ~/.nodevm
Your machine's original Node behaviour returns, with no leftover files or config.
Scripting
Every command that reports data supports --json with a stable documented shape. Data goes to stdout;
errors, warnings, progress and all interactive UI go to stderr, so nodevm ls | grep 20 works. Exit
codes: 0 success, 2 usage, 3 version not found, 4 no build for this platform, 5 checksum
mismatch, 6 network unavailable, 7 store error, 8 Node too old to run nodevm.
--json and --silent both force non-interactive mode: nodevm never waits for input that cannot
arrive.
License
MIT