Home

Awesome

.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):

Other products which read .node-version include:

(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:

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

Utilitysimpleleading vpartialUnix EOLNo EOLWin EOLNotes
20.5.0v20.5.020.5
asdf:white_check_mark::white_check_mark::x::white_check_mark::white_check_mark::x:
avn:white_check_mark::white_check_mark::white_check_mark::white_check_mark::white_check_mark::white_check_mark::ghost: #11
chnode:white_check_mark::white_check_mark::white_check_mark::white_check_mark::white_check_mark::white_check_mark:
dev:white_check_mark::white_check_mark::white_check_mark::white_check_mark::white_check_mark::white_check_mark:
direnv:white_check_mark::white_check_mark::white_check_mark::white_check_mark::white_check_mark::x:
fnm:white_check_mark::white_check_mark::white_check_mark::white_check_mark::white_check_mark::white_check_mark:
mise:white_check_mark::white_check_mark::white_check_mark::white_check_mark::white_check_mark::white_check_mark:
n:white_check_mark::white_check_mark::white_check_mark::white_check_mark::white_check_mark::white_check_mark:
nodeenv:white_check_mark::white_check_mark::x::white_check_mark::white_check_mark::white_check_mark:
nenv:white_check_mark:🧩 #8🧩 #8:white_check_mark::white_check_mark::white_check_mark:
nodenv:white_check_mark::white_check_mark:🧩 #1:white_check_mark::white_check_mark::white_check_mark:
nodist:white_check_mark::white_check_mark::white_check_mark::white_check_mark::white_check_mark::white_check_mark:
nve:white_check_mark::white_check_mark::white_check_mark::white_check_mark::white_check_mark::white_check_mark:
nvm-rust:white_check_mark::white_check_mark::white_check_mark::white_check_mark::white_check_mark::white_check_mark:
nvm.fish:white_check_mark::white_check_mark::white_check_mark::white_check_mark::white_check_mark::x:
nvs:white_check_mark::white_check_mark::white_check_mark::white_check_mark::white_check_mark::white_check_mark:
setup-node:white_check_mark::white_check_mark::white_check_mark::white_check_mark::white_check_mark::white_check_mark:
vfox:white_check_mark::white_check_mark::white_check_mark::white_check_mark::white_check_mark::white_check_mark:

The columns show whether the utility supports a file containing:

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.)

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.

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