nodenv: Pin a Node Version with .node-version
nodenv install <version> installs Node and nodenv local writes .node-version, with shims dispatching node/npm to the pinned version.
nodenv is the rbenv-style Node manager: shim-based, with a .node-version pin and an init eval. It coexists cleanly with other rbenv-family tools because they share the same architecture.
What it does
nodenv intercepts node, npm, and npx via shims and runs the version chosen by .node-version (local), the global setting, or NODENV_VERSION. nodenv install (via the node-build plugin) downloads and installs a Node version.
Common usage
export PATH="$HOME/.nodenv/bin:$PATH"
eval "$(nodenv init -)"
nodenv install 20.11.1
nodenv local 20.11.1 # writes .node-version
node -vOptions
| Command / flag | What it does |
|---|---|
| nodenv install <v> | Install a Node version (needs node-build) |
| nodenv install -s <v> | Skip if already installed |
| nodenv local <v> | Write .node-version for this directory |
| nodenv global <v> | Set the default Node version |
| nodenv rehash | Regenerate shims after installing CLI packages |
| eval "$(nodenv init -)" | Add nodenv shims to PATH |
In CI
Eval nodenv init - in each step. After a global npm install -g of a package with a binary, run nodenv rehash or its shim is missing. Cache ~/.nodenv/versions. Use nodenv install -s so re-runs do not reinstall.
Common errors in CI
"nodenv: node: command not found" means init was not eval'd or a rehash is needed. "nodenv: version 20.11.1' is not installed" means the pin points at an uninstalled version; run nodenv install. "nodenv: no such command 'install'" means the node-build plugin is missing under $(nodenv root)/plugins`.