fnm: Fast Node Manager with --use-on-cd
fnm is a single Rust binary that switches Node versions in milliseconds and, with --use-on-cd, auto-switches when you enter a directory with a .node-version or .nvmrc.
fnm is the fast alternative to nvm. Because it is a real binary on PATH it avoids the "command not found" sourcing trap, but you still need to evaluate fnm env to activate version switching in a shell.
What it does
fnm installs Node versions and switches between them by managing a multishell symlink on PATH. fnm env prints the shell setup; with --use-on-cd it adds a hook so changing into a project directory automatically applies its .node-version or .nvmrc.
Common usage
# install the binary, then activate in the shell
eval "$(fnm env --use-on-cd)"
fnm install 20.11.1
fnm use 20.11.1 # or just cd into a dir with .node-version
node -v
fnm install --lts && fnm default lts-latestOptions
| Command / flag | What it does |
|---|---|
| fnm install <v> | Install a Node version |
| fnm use <v> | Switch the active version |
| fnm env | Print shell init; eval it to activate fnm |
| --use-on-cd | Auto-switch version on directory change |
| fnm default <v> | Set the default version for new shells |
| --version-file-strategy | local or recursive .node-version lookup |
In CI
Run eval "$(fnm env)" once per step (PATH does not persist across steps). You can skip --use-on-cd in CI and call fnm use explicitly, which is more predictable than relying on a cd hook. The fnm install reads .node-version if you pass no version.
Common errors in CI
"error: Can't find an installed Node version matching" from fnm use means the version is not installed yet; run fnm install first. "fnm: command not found" means the binary is not on PATH (the install dir was not added) - this is an install/PATH issue, not a sourcing one like nvm. If switching seems to do nothing, you forgot eval "$(fnm env)".