HOWTO Use nvm on GitHub Actions

Last update: 2024-08-31

Note

actions/setup-node now supports nvm-compatible Node version specifications. To activate this:

- uses: actions/setup-node@v4
  with:
    node-version-file: ".nvmrc"

This also builds in support for caching — see the documentation.

The original article from 2021 continues below.

nvm — Node Version Manager — is a tool that manages Node JS installations. It lets you declare the required Node version in a .nvmrc file and type nvm use to use it, automatically downloading if necessary.

GitHub Actions is a continuous integration service built into GitHub. nvm is preinstalled in many of GitHub Actions' default Virtual Environments (virtual machines).

The Wrong Way

However, if you try to use the nvm command in a job step it won't work. Here's a naïve example:

steps:
- run: nvm install

This will fail with an error like:

nvm: command not found

Why doesn't the nvm command work by default? Recall that when you install nvm it adds a snippet to your shell's startup scripts. For Bash, it's added to ~/.bash_profile, which is only sourced (included) as part of interactive shell startup [1]. A GHA run step runs Bash with flags that skip sourcing that file, by default:

bash --noprofile --norc -eo pipefail {0}

If you override the shell command to include the --login flag Bash will automatically do the sourcing:

jobs:
 steps:
 - run: |
     nvm install
   shell: "bash -eo pipefail --login {0}"

This is a bit of a mouthful to repeat on each step, but that's what it takes.

Enabling Caching

You also have to manually wire up actions/cache to cache the Node install and package dependencies. See a fully-worked example.

[1]	See the INVOCATION section of `bash(1)`