How to automate switching Node.js versions with nvm and zsh

About 2 min reading time

As a frontend developer, you may find yourself working on projects that require different versions of Node.js. Manually switching between versions can be tedious and easy to forget, especially if you're working on multiple projects simultaneously. Fortunately, there's a way to automate switching to the correct Node.js version whenever you enter the project directory. In this post, I'll show you how to set up auto-switching using nvm and zsh.


Before we dive in, you'll need to have the following installed on your machine:

  • zsh
  • nvm (Node Version Manager)

If you don't have nvm installed, you can find instructions on the nvm GitHub page.

Setting up auto-switching

Assuming you have nvm and Zsh installed, here's how to set up auto-switching:

  1. In the root directory of your project, create a .nvmrc file and add the version of Node.js you want to use. For example, if your project requires Node.js version 18.15.0, add 18.15.0 to the .nvmrc file.

  2. Open your .zshrc file in your favorite text editor (e.g. vim ~/.zshrc).

  3. Add the following lines at the end of the .zshrc file:

autoload -U add-zsh-hook
load-nvmrc() {
  local node_version="$(nvm version)"
  local nvmrc_path="$(nvm_find_nvmrc)"

  if [ -n "$nvmrc_path" ]; then
    local nvmrc_node_version=$(nvm version "$(cat "${nvmrc_path}")")

    if [ "$nvmrc_node_version" = "N/A" ]; then
      nvm install
    elif [ "$nvmrc_node_version" != "$node_version" ]; then
      nvm use
  elif [ "$node_version" != "$(nvm version default)" ]; then
    echo "Reverting to nvm default version"
    nvm use default
add-zsh-hook chpwd load-nvmrc
  1. Save and close the .zshrc file.

  2. Restart your terminal or run source ~/.zshrc for the changes to take effect.

That's it! Now, whenever you enter your project's directory, the zsh-hook we defined in your ~/.zshrc file will automatically switch to the Node.js version specified in the project's .nvmrc file. This ensures that you are always using the correct version of Node.js for your project without needing to manually switch versions every time you enter the directory. In every other directory this will switch to your default Node.js version.

I hope this post has been helpful. If you know a better alternative, please reach out to me on Mastodon. Happy coding!

This post is based on my opinion and experience. It is based on what worked for me in my context. I recognize, that your context is different.
The "Just Sharing" Principle