.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

Other Formats

The compatibility table deliberately only covers commonly supported formats and is not intended to be a full feature table.

Some utilities do support version specifiers beyond just a numeric version. Often utilities read the .node-version file contents and then use their normal version parsing code. Some recognise Node.js codenames (like Jod), or convenience targets like lts.

There is not wide support for comments in the .node-version file, whether on the same line or a separate line.

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