Installation
Requirements
Section titled “Requirements”- Windows on x64.
- macOS on Apple silicon or Intel. The sandbox uses
sandbox-exec, which ships with macOS. - Linux on x86_64 or arm64. The sandbox needs kernel 5.13 or later with
Landlock enabled and unprivileged user namespaces. The network allowlist also
needs the
ipcommand from iproute2. When one is missing, contained commands refuse to run, so nothing runs uncontained.
nvx is one static binary and needs nothing installed alongside it.
Windows
Section titled “Windows”irm https://nvx.run/install.ps1 | iexReleases from 0.7.0 are Authenticode-signed. SmartScreen also judges a download by its reputation. A certificate builds that up as people download what it signed, so early signed releases can still show “Windows protected your PC”. Defender has also flagged unsigned builds as malware by machine learning, because nvx rewrites permissions and creates sandbox tokens the way some malware does.
macOS and Linux
Section titled “macOS and Linux”curl -fsSL https://nvx.run/install.sh | shRead a script before piping it to a shell. What the installer changes lists everything these two write.
Check it worked
Section titled “Check it worked”Open a new terminal, because an installer that changed PATH cannot change it
for a shell that is already running. Then run:
nvx install 22nvx use 22nvx doctornvx doctor reports whether the shims are intercepting, whether your shell loads
the integration, and whether anything on the machine weakens containment. It
exits non-zero when something needs your attention, and nvx doctor --fix
repairs what it safely can.
What the installer changes
Section titled “What the installer changes”- Creates
~/.nvxand puts a single binary in~/.nvx/bin. - Puts
~/.nvx/binat the front of your userPATH. - Adds the shell integration to your profile. That is what makes
nvx useaffect your shell and what switchesPATHoncd. Without it the shims still run the version each project pins, andnvx usedoes nothing.install.shadds a three-line block. It holds a comment, a line putting~/.nvx/binonPATH, andeval "$(nvx env)". For bash it writes the block to~/.bashrcand to your login profile, for zsh to~/.zshrc, and otherwise to~/.profile. For fish it writes its own file,~/.config/fish/conf.d/nvx.fish, in fish syntax, and touches nothing else.install.ps1adds one integration line, with a comment above it, to your PowerShell$PROFILE.
- On Windows, asks before changing your PowerShell execution policy.
Declining still installs nvx. The shell integration then needs
Set-ExecutionPolicy RemoteSigned -Scope CurrentUserbefore a profile can load at all.
cmd.exe has no profile, so nothing is written for it. With ~/.nvx/bin on your
user PATH the shims run each project’s pinned version in a cmd window.
nvx use cannot switch a cmd window by itself, and says so. nvx default <version> sets the version new windows start on, and
Commands has the one-line command that switches a
single window.
Prebuilt binaries
Section titled “Prebuilt binaries”nvx is on npm as @fstubner/nvx. It installs only the binary for your
platform and runs no install script:
npm install -g @fstubner/nvxIt is not yet published to winget, Scoop or Homebrew. The other route is a binary. Every release attaches one per platform, each with a SHA-256 sidecar. The platforms are Windows x64, macOS on Apple silicon and Intel, and Linux on x86_64 and arm64.
Verify a download
Section titled “Verify a download”Each of those five binaries carries a signed build attestation, made by the
release workflow in this repository. With the GitHub CLI (2.49 or newer, signed
in with gh auth login), check the file you downloaded:
gh attestation verify nvx-linux-amd64 --repo fstubner/nvxUse your own file name. If the command reports a failure, do not run the file.
The .sha256 file beside each binary holds the file’s SHA-256. It comes from the
same release page as the binary, so it catches a damaged download and does not
prove who built the file. Compare it from the directory holding both files.
On Linux:
sha256sum -c nvx-linux-amd64.sha256On macOS:
shasum -a 256 -c nvx-darwin-arm64.sha256On Windows:
(Get-FileHash nvx.exe -Algorithm SHA256).Hash -ieq ((Get-Content nvx.exe.sha256) -split '\s+')[0]That prints True when they match. When the GitHub CLI is installed, signed in
and 2.49 or newer, install.sh and install.ps1 run the attestation check
before they install the download. They stop if it fails. Without it they say
the check was skipped and print the command to run.
From source
Section titled “From source”go build -o nvx ./cmd/nvxBehind a corporate proxy or mirror
Section titled “Behind a corporate proxy or mirror”nvx reads HTTPS_PROXY, HTTP_PROXY and NO_PROXY like other tools, and
contained installs go through the same proxy once nvx’s allowlist has approved
the host. To fetch Node.js from an internal mirror, set NVX_NODE_MIRROR to its
dist URL. An existing NVM_NODEJS_ORG_MIRROR or FNM_NODE_DIST_MIRROR works
too. The pre-install checks use the registry your .npmrc names. See
Corporate networks for what each of these
does and which hosts nvx contacts.
Uninstall
Section titled “Uninstall”- If you ever ran
nvx setupon Windows, runnvx setup --undofrom an Administrator terminal. That removes the drive-root andUsersfolder grants it added. - Run
nvx grants reset --allto withdraw the read and execute permissions granted forallow_read_execentries, and to forget approved grants. - Delete
~/.nvx. - Remove the nvx lines from your shell profile, or from
$PROFILEon Windows. - On Windows, remove
%USERPROFILE%\.nvx\binfrom your userPathvariable.