.node-version File Usage

Q: Is .node-version read by multiple Node.js version managers?
A: Yes.

Q: Does .node-version have a defined common or standard file format?
A: No.

Q: So what compatibility is there across individual products?
A: Good question! Read on...

Supporting Products

Version managers for Node.js which read a .node-version file include (in alphabetical order):

• asdf-nodejs Node.js plugin for asdf version manager. (macOS, Linux)
• avn Automatic Version Switching for Node. (macOS, Linux)
• chnode Changes shell's current Node.js version by updating $PATH (macOS, Linux)
• dev dev is built on pkgx, a single, standalone binary that can run anything (macOS, Linux)
• direnv unclutter your .profile. (macOS, Linux)
• fnm 🚀 Fast and simple Node.js version manager, built in Rust. (macOS, Linux, Windows)
• mise Polyglot switcher compatible with asdf plugins, built in Rust. (macOS, Linux)
• n Interactively Manage Your Node.js Versions. (macOS, Linux)
• nenv Groom your app’s Node environment with nenv (macOS, Linux)
• nodeenv Virtual environment for Node.js & integrator with virtualenv (macOS, Linux, Windows)
• nodenv Manage multiple NodeJS versions. (macOS, Linux)
• nodist Natural node.js and npm version manager for windows. (Windows)
• nve Run any command on specific Node.js versions (macOS, Linux, Windows)
• nvm-rust A cross-platform node version manager that doesn't suck (macOS, Linux, Windows)
• nvm.fish Node.js version manager lovingly made for Fish. (macOS, Linux)
• nvs Node Version Switcher - A cross-platform tool for switching between versions and forks of Node.js. (macOS, Linux, Windows)
• setup-node (configuration) Set up your GitHub Actions workflow with a specific version of node.js
• vfox The Multiple SDK Version Manager

Other products which use .node-version include:

• bitrise The CI/CD Platform built for Mobile DevOps
• Cloudflare Pages Build fast sites. In record time.
• Hostman Hosting platform that deploys your web applications
• netlify Instantly build and deploy your sites to our global network from Git.
• paketo Your app, in your favorite language, ready to run in the cloud
• preferred-node-version Get the preferred Node.js version of a project or user
• Pulumi Deployments Automate, Secure, and Manage Everything You Run in the Cloud
• ReadyMage Magento 2 and PWA managed auto-scalable infrastructure hosting service.
• render A Cloud for the New Decade
• Spaceship Minimalistic, powerful and extremely customizable Zsh prompt
• starship ☄🌌️ The minimal, blazing-fast, and infinitely customizable prompt for any shell!
• typescript-action Create a TypeScript Action with tests, linting, workflow, publishing, and versioning
• Vercel Conformance Conformance provides tools that run automated checks on your code for product critical issues, such as performance, security, and code health.
• VMware Tanzu The Tanzu Node.js Buildpack supports several popular configurations for Node.js apps.

(Note: nvm does not support reading a .node-version file. See #4 for more.)

Suggested Compatible Format

If you are creating the file, a format with full compatibility across current tests is:

• single line with unix line ending
• three part numeric version e.g. 14.5.0

A leading 'v' is widely supported, so this will work with most implementations:

$ node --version
v20.12.0
$ node --version > .node-version

If you are reading the file in a new implementation, I suggest you also support optional leading v and any line ending. Allowing a leading v is common and gives nice symmetry with node --version. Allowing any line ending makes it easier for users and especially Windows users to create a file compatible with your product.

Compatibility Testing

Utility	simple	leading v	partial	Unix EOL	No EOL	Win EOL	Notes
	20.5.0	v20.5.0	20.5
asdf	✅	✅	❌	✅	✅	❌
avn	✅	✅	✅	✅	✅	✅	👻 #11
chnode	✅	✅	✅	✅	✅	✅
dev	✅	✅	✅	✅	✅	✅
direnv	✅	✅	✅	✅	✅	❌
fnm	✅	✅	✅	✅	✅	✅
mise	✅	✅	✅	✅	✅	✅
n	✅	✅	✅	✅	✅	✅
nodeenv	✅	✅	❌	✅	✅	✅
nenv	✅	🧩 #8	🧩 #8	✅	✅	✅
nodenv	✅	✅	🧩 #1	✅	✅	✅
nodist	✅	✅	✅	✅	✅	✅
nve	✅	✅	✅	✅	✅	✅
nvm-rust	✅	✅	✅	✅	✅	✅
nvm.fish	✅	✅	✅	✅	✅	❌
nvs	✅	✅	✅	✅	✅	✅
setup-node	✅	✅	✅	✅	✅	✅
vfox	✅	✅	✅	✅	✅	✅

The columns show whether the utility supports a file containing:

• simple: three part numeric version, like 20.5.0
• leading v: numeric version with a leading v, like v20.5.0
• partial: numeric version with less than three parts, like 20.5
• EOL: end of line characters used in file, Unix \n or Windows \r\n or none

References

For interest, here are discussion about similar .ruby-version file format. The commonly supported format is a simple version, with many products adding fuzzy matching. (Ruby is likely the inspiration for some of the .node-version usage, especially nodenv which uses rbenv syntax.)

• https://gist.github.com/fnichol/1912050
• https://github.com/orgs/rubygems/discussions/7074

A discussion about a possible standard format for .node-version was started in 2016 initially covering desirable (new) features and then more focus on existing usage, but did not reach consensus.

• nodejs/version-management#13

StackOverflow: What uses / respects the .node-version file?

• https://stackoverflow.com/questions/27425852/what-uses-respects-the-node-version-file