If you've been working with Node for a while, you will most likely discover that your projects – or one you're working on – are written for an older version of Node. That means they won't work as expected with the latest version.

In that case, a Node version manager can help you save precious time installing and switching back and forth between different Node versions.

Today I will introduce you to fnm(Fast Node Manager), a Node version manager, written in Rust with simplicity and speed in mind. fnm also has cross platform support.

Table of contents

1Installation for Linux system and zsh shell §

Here I will only cover the installation of fnm for Linux systems and the zsh shell. See the documentation for installation instructions for other platforms and shells.

First make sure curl is installed on your system. Then run the following to install fnm:

curl -fsSL https://fnm.vercel.app/install | bash -s -- --skip-shell

It will install fnm in your $HOME/.fnm/ directory.

Updating fnm is the same as installing it again with the above command.

1.1Shell setup §

There is one more important step. Just add the following to your .zshrc file:

# fnm
export PATH=/home/$USER/.fnm:$PATH
eval "$(fnm env --use-on-cd --version-file-strategy=recursive)"

1.2How to install the completion script §

Installing the completion script is optional. If you're wondering about the role of this step, here is what it does: it tries to auto-complete the partial command that you type relating to fnm when you press the TAB key. For example if you type fnm ls- and press the TAB key it will auto-complete to fnm ls-remote.

fnm comes with all the completion codes for different shells with its binary. You will have to paste that code in a file named _fnm in a directory specified in the FPATH environment variable:

fnm completions --shell zsh > <a_fpath_dir>/_fnm

See the output of echo $FPATH to get all the possible directories and replace <a_fpath_dir> with an actual directory. It is recommend to use a user local path. If there are no such path, you can set one in your .zshrc by adding this line:

fpath=(/home/$USER/your/favorite/path/here $fpath)

2Common usage of fnm §

2.1How to list all remote Node versions §

To see all the different Node versions you can install, run:

fnm ls-remote

It will print all the versions like below:

.
.
.
v16.15.0 (Gallium)
v16.15.1 (Gallium)
v17.0.0
v17.0.1
v17.1.0
v17.2.0
v17.3.0
v17.3.1
v17.4.0
v17.5.0
v17.6.0
v17.7.0
v17.7.1
v17.7.2
v17.8.0
v17.9.0
v17.9.1
v18.0.0
v18.1.0
v18.2.0
v18.3.0

2.2How to install multiple versions of Node §

Let's install Node of version v18.3.0:

fnm install v18.3.0

For installing Node of the latest LTS version, you can use the --lts option. So run the following to install it also:

fnm install --lts

fnm also supports partial version matching. fnm guesses the latest available version from your partial input. For example, if you just do:

fnm install 17

It will install the Node of version v17.9.1 which is latest available version starting with 17. So experiment with the above command.

Let's check your Node version by entering node --version in your terminal. Note that the first installed one is used by default.

Before seeing how to start using a different installed version of Node, let's see how you can set an alias(name) to a version so that you can refer to it easily.

2.3How to set aliases for a Node version §

By default, the first version of Node that you install using fnm receives the default alias.

The syntax to set an alias for a version is:

fnm alias <version> <name>

If you want to set the alias default, there is a shorthand:

fnm default <version>

You can set multiple aliases for a version, too.

The syntax to remove an alias is:

fnm unalias <name>

2.4How to use a particular version of Node §

You can use a Node of a particular version using the use sub-command:

fnm use 16

To check the current Node version, simply run:

fnm current

To list all the Node versions that you installed with fnm, run:

fnm ls
fnm-ls-1

Note that you can bypass fnm and use the system wide installation of Node on your system (if any) by using the system:

fnm use system

2.5How to attach a Node version to a project §

You can create a .node-version file in the root of your project and just write the desired Node version of that project in that file like below to attach a Node version to it:

echo 'v18.3.0' > .node-version

fnm respects this file. So if you are in that directory, you can just use fnm install or fnm use to install or use that version.

fnm also respects the .nvmrc file (it is similar to the .node-version file but came from nvm land). So if you used nvm earlier, you will have smooth transition to fnm.

fnm can use these dot files to detect Node version and even start using it automatically when using cd, which is really handy in most cases, so I've already enabled them in the shell setup by adding the following flags to the fnm env command:

  • --use-on-cd: This flag tells fnm that when you cd into a project root directory, it should automatically use the Node of version specified in .node-version(or .nvmrc). Cool, isn't it?
  • --version-file-strategy=recursive: This flag and the recursive value of it basically tells fnm to use the specified Node version in .node-version(or .nvmrc) even when you are in a nested directory and using the use or install sub-command without a version. It also tells fnm to use the Node version aliased to default when you are out of any such project directory and using the use sub-command without a version. Using this flag along with --use-on-cd allows you to have the magic of automatically using or installing the Node of the relevant version(as described here) when you go deeply in and out of such project directories.

If these features interfere your workflow, you can remove these flag(s) anytime in your shell setup to turn them off.

2.6How to uninstall a version of Node §

Uninstalling a version of node is very similar to installing it. You just need to use sub-command uninstall instead of install. That's it.

3How to remove fnm §

Removing fnm is as simple as removing the .fnm directory from your home and removing its specific config that you added in your shell config file. Remember to also remove the completion script.

4Summary §

Below is a summary of all the commands we have discussed in this article:

# Listing all remote versions
fnm ls-remote

# Listing all installed ones
fnm ls

# Installing
fnm install <version>

# Uninstalling
fnm uninstall <version>

# Installing node of the latest LTS version
fnm install --lts

# Setting an alias
fnm alias <version> <name>

# Shortcut for setting 'default' as an alias
fnm default <version>

# Removing an alias
fnm unalias <name>

# Using a Node of a particular version
fnm use <version>

# Displaying the version of currently used Node
fnm current

Also, if you need quick help, fnm has built in help that you can get at any time right from your terminal like below:

  • Help for the fnm command: fnm --help
  • Help for any sub command fnm <sub-command> --help

If you like fnm don't forget it give it a star on GitHub. I think it deserves more stars than it has now.

Thanks for reading! If you want you can checkout my website and follow me on Twitter and LinkedIn.

Happy Coding 😄