NVS (Node Version Switcher): Installing and Using jasongin/nvs for Node.js Version Switching

What NVS solves, and who ends up using it

Node.js projects do not agree on a runtime version. One service needs an LTS line, a library you are patching needs an older major, and a CI job needs to check both. NVS exists to make that switching cheap: it downloads Node builds, keeps them side by side under a single home directory, and rewrites your PATH so the shell in front of you points at the version you asked for.

The audience is narrower than the description suggests. NVS is written in node JavaScript, so it is itself a Node program that manages Node installations, which means the bootstrap step has to work before the tool does. The README addresses that directly on Mac and Linux by having you clone the repository and source a shell script, and on Windows by shipping an installer. If you work on one operating system only and already have a working nvm setup, NVS is not obviously worth the migration. If you move between Windows and a Unix shell, or you maintain CI matrices, the cross-platform promise is the reason to look at it.

How the version resolution and PATH switching actually work

The README describes a version or filter as a complete or partial semantic version number or a version label such as lts, latest or Argon, optionally preceded by a remote name and optionally followed by an architecture, separated by slashes. That is the whole addressing scheme: "6/x86" and "node/6.7/x64" are both valid, and the remote segment defaults to the default remote when you leave it out.

The installation layout follows from the same idea. `nvs which myalias` returns a path of the form ~/.nvs/node/6.7.0/x64/bin/node, so the tree is home directory, then node, then version, then architecture, then the usual bin directory. Because the architecture is part of the path, a 32-bit and a 64-bit build of the same version coexist without colliding. Remotes are managed separately for the same reason: the README states that NVS manages versions from different remote locations separately, so there is no risk of version collisions between them.

Switching is not a symlink swap in the nvm sense. `nvs use` modifies PATH for the current shell, and the README shows the resulting line, PATH += ~/.nvs/node/6.9.1/x64. Making that permanent is a separate command, `nvs link`, which links a version as the default. There is also `nvs auto [on/off]`, which switches automatically based on the current working directory. The distinction matters when you debug a shell that reports the wrong node: the question is whether you ran use in that shell, whether you ran link at some point, or whether auto is on and picked up a directory marker.

Installing NVS on Windows, Mac and Linux

On Windows the README points at three routes: an MSI package from the NVS releases page on GitHub, winget, and chocolatey. The winget command is a single line and is available by default on Windows 11.

winget install jasongin.nvs

After it completes you should have an `nvs` command on PATH. The chocolatey route is `choco install nvs` for machines where chocolatey is already the package manager.

On Mac and Linux the README gives a three-step sequence: set NVS_HOME, clone the repository into it, and source the install command from the cloned nvs.sh.

export NVS_HOME="$HOME/.nvs"
git clone https://github.com/jasongin/nvs "$NVS_HOME"
. "$NVS_HOME/nvs.sh" install

The install step is the part people skip reading. It adds lines to your ~/.bashrc, ~/.profile or ~/.zshrc so that nvs.sh is sourced in future shells, and it defines an `nvs` shell function. The README is explicit that afterward the tool should be invoked as just `nvs` without any path. For ksh, the source line has to go in your ~/.kshrc or wherever $ENV points, which the README notes separately because the automatic profile editing does not cover it.

A first real use is short. Add the latest LTS build, then put it on PATH for the current shell.

nvs add lts
nvs use lts

The README shows the second command printing the PATH addition, so seeing a line like `PATH += ~/.nvs/node/6.9.1/x64` is the expected result rather than an error. If you want that version to be the default in every new shell, run `nvs link lts` instead of relying on `use`. To see what is already installed locally, `nvs ls` lists local versions and `nvs ls-remote [filter]` lists versions available to download.

Remotes and aliases: the two features that justify NVS over nvm

The `nvs remote` command configures named download locations. Out of the box there is one remote pointing at official Node.js releases, and `nvs remote` with no arguments prints it, showing the name `node` and the base URI https://nodejs.org/dist/. You can add others, and the README walks through nightly builds.

nvs remote add nightly https://nodejs.org/download/nightly/
nvs lsr nightly/13
nvs add nightly/13

The listing step returns entries such as nightly/13.1.1-nightly20191120c7c566023f, which is the naming you will pass back into `nvs add`. The README also gives iojs and chakracore as further examples, pointing at https://iojs.org/dist/ and https://nodejs.org/download/chakracore-release/ respectively. This is the capability nvm does not offer in the same form: nvm is tied to the Node.js distribution channel, while NVS treats the download base URI as configuration.

Aliases sit on top of the same addressing model. An alias refers to a combination of a remote name and a semantic version, and the README notes that processor architectures are not aliased. When you set one, the remote name may be omitted, in which case the alias refers to the default remote. The example sets `nvs alias myalias 6.7.0`, and `nvs alias` with no arguments recalls it as `myalias default/6.7.0`. From there the alias works anywhere a version string does, including `nvs run myalias --version` and `nvs which myalias`. Because the architecture is not part of the alias, `nvs which myalias/32` resolves the same version to the x86 binary. That is a deliberate design choice, and it is also a sharp edge: an alias that hides the architecture can send a 32-bit build into a script that assumed 64-bit.

Where NVS is the wrong tool, and what to use instead

The clearest limitation is that NVS is not a per-project lockfile mechanism. There is a `.node-version` file mentioned in the VS Code section, which lets the editor pick up a version from the project directory, and `nvs auto` switches on directory change. Neither is described in the README as a reproducibility guarantee across machines. If your requirement is that every developer and every CI runner gets a byte-identical runtime, a version manager that mutates PATH is a weaker fit than pinning the runtime in the build image or in the project's own tooling.

The natural alternative is nvm, which the README names as the inspiration and credits for both ideas and some command-line syntax. The difference in approach is scope. nvm is a Unix shell tool; NVS is a JavaScript program with a Windows installer, a winget package and a chocolatey package, and the README frames it as cross-platform from the first line. If your team is entirely on macOS and Linux and already standardized on nvm, switching buys you the remote configuration and the interactive menu, and costs you a migration of every profile file and every habit. The README also notes that the interactive menu comes from console-menu, a module originally written for this project and then published separately, so the menu is a first-party component rather than a wrapper around something else.

A second limitation is documentation depth. The README repeatedly defers to the docs directory, for example stating that setup details and options live in doc/SETUP.md and that per-command details are in ./doc. The README itself is a command table plus a handful of worked examples. The README does not document rollback, and it does not describe what happens to already-installed versions when you change a remote's URI. Treat the command table as an index, not as a specification.

Maintenance, release cadence and the licence question

The repository is not archived, and the last push was on 2026-09-13. That is recent enough that the code is being touched, but the release list tells a different story: v1.7.1 is dated 2023-08-16, v1.7.0 is dated 2022-12-07, and v1.6.2 is dated 2022-04-20. The package.json in the repository declares version 1.8.0, which is ahead of the newest published release in that list. If you install from a package manager or from a release artifact, you may be getting a different version than the one the repository's package.json describes. Check `nvs --version` after installation rather than assuming.

Upgrade cost is low in one direction and uncertain in another. `nvs upgrade [fromver]` upgrades to the latest patch of a major version, so staying current within a major line is a single command. Moving between major lines means adding a new version and re-linking, and `nvs migrate <fromver> [tover]` exists to migrate global modules, which is the step people forget and then wonder why their globally installed CLI is missing. The README does not document rollback, so if an upgrade breaks your global module set, you are reconstructing it rather than reverting it.

On licensing, the repository contains a LICENSE.txt at the top level and the package.json declares "license": "MIT", while the repository metadata reports NOASSERTION. Those two signals disagree, and the practical consequence is that you should read LICENSE.txt yourself before redistributing NVS inside a product image. This is a description of what the files say, not legal advice.

Editorial conclusion

Adopt NVS if you need one version manager across Windows, macOS and Linux, or if you want to pull Node builds from a source other than nodejs.org through nvs remote. Do not adopt it if you need a documented rollback path, because the README does not describe one, or if you expect the project to be actively developed: the last push was on 2026-09-13, but the newest release listed is v1.7.1 from 2023-08-16, so the release cadence is slow. Verify two things before committing: that the nvs shell function is actually available in a new shell after installation, and that the version your build needs resolves through nvs ls-remote.

Frequently asked questions

Official sources

1. Issues
2. jasongin/nvs on GitHub
3. README
4. Releases