How to Use Multiple Node Version With asdf.

Switching between different node versions has never been easier.

Listen to this article

If you work a lot with Node projects, it often happens that you need to change the Node version. Older projects may still be running on Node 10 or 12, while newer ones already use Node 14. To quickly switch between versions, many people use nvm (node version manager). nvm is a well-tried and well-known version manager for Node (like pyenv or virtualenv for Python). I myself used nvm for years until I was finally introduced to asdf. asdf has become my favorite and has replaced all other version managers because asdf supports multiple languages at once (Ruby, Node.js, Python, Elixir, Erlang & more)!

You may think that a handstand is necessary to use asdf as the primary version manager, but I can assure you that is not necessary. With a few commands (FTR: I only talk about macOS in this article) you have asdf installed and ready to go.


On their website, select your operating system and installation method. For this tutorial, I have chosen macOS and Homebrew. Execute the following commands in this order to install and set up asdf:

# install required dependencies
brew install coreutils curl git

# install asdf
brew install asdf

# add it to your shell
echo -e "\n. $(brew --prefix asdf)/" >> ~/.bash_profile

# set up bash completions
echo -e "\n. $(brew --prefix asdf)/etc/bash_completion.d/asdf.bash" >> ~/.bash_profile

Once you have installed the commands you should see which version you have installed when executing asdf --version. In my case, I get v0.8.0.

How to Install Plugins and Versions

One thing you need to know about asdf is that each supported language requires a plugin which in turn manages the versions of the language. Therefore, you must first install the necessary plugin and then the versions. Let's see how this looks like for Node.js.

# install the package
asdf plugin add <name>
# asdf plugin add nodejs

# get a list of installed plugins
asdf plugin list

# update plugin(s)
asdf plugin update <name>
asdf plugin update --all

# remove plugin
asdf plugin remove <name>
# asdf plugin remove nodejs

Now that we have Node.js installed, let's see how we can install one or more versions. Again, this can be done with a few simple commands.

# install version for package
asdf install <name> <version>
# asdf install nodejs 14.15.4

# list installed versions
asdf list <name>

# list all versions
asdf list all <name>

How To Set the Current Plugin Version

Once you installed the plugin nodejs with the required version you can choose to either set and use this version globally, in your current shell, or in the current project folder.

asdf global <name> <version> [<version>...]
asdf shell <name> <version> [<version>...]
asdf local <name> <version> [<version>...]
# asdf global nodejs 14.15.4

asdf global will write the selected version to $HOME/.tool-versions (docs). asdf shell only to the current shell, which can be different compared to other shells. asdf local writes the version to $PWD/.tool-versions. This is the file I check in in my repositories (example) to share the used versions of a project with other contributors.

When you set the version globally or locally you can verify that asdf has selected the proper version by running node --version. It should automatically switch it based on your settings now.

You do not need to add a script to your .bash_profile to do this automatically as you have with nvm(this is how you do this with nvm).

Legacy Support

You may ask yourself how you can use asdf when other colleagues still use nvm, do you? It is possible thanks to the legacy support asdf provides. Add a .asdfrc file to your home directory and specify the following settings. This will enable legacy support for files like .node-version or .nvmrc.

# .asdfrc
legacy_version_file = yes

But I am sure that you will want to ask your colleagues to switch to asdf too, once you got used to it. That's what I did at least.


Because asdf supports multiple languages almost out of the box, you can remove almost all the other version managers or gradually move to asdf. I highly recommend asdf, since it has made version management a lot easier for me. Check out their well-written docs for more details.

Feel free to reach out to me on Twitter or in the comments below if you have more questions and input.

Share 💛

Do you like this article? Do you want to support me? Tell your friends on Twitter about it. Thank you!

Questions and Feedback

You got any questions or want to add your thoughts? Let me know in the comments below, please.

Let's connect

No Comments Yet