Switching Node.js Versions with NVM on macOS Executors

Overview

CircleCI’s macOS executor images (Xcode) come with nvm (Node Version Manager) pre-installed and fully configured. This makes it easy to switch between different Node.js versions in your CI workflow using a single command.

Using `nvm` to Switch Node.js Versions

Key Information

No setup or sourcing is required — nvm is ready to use.
You can use nvm install to install a Node.js version and nvm use to switch to it.

Example Configuration

version: 2.1

jobs:
  build:
    macos:
      xcode: "14.2.0"  # Choose any supported Xcode image
    steps:
      - checkout

      - run:
          name: Use Node.js 20
          command: |
            nvm install 20
            nvm use 20
            node -v
            npm -v

      - run:
          name: Run tests
          command: |
            nvm use 20
            npm test

✅ Tip: nvm is available in the shell environment by default on all Xcode macOS executor images — no need to source it or define NVM_DIR.

Summary

You can switch between Node.js versions effortlessly on CircleCI macOS executors using nvm install and nvm use. This is a convenient way to test against multiple versions of Node.js or align with your project's specific requirements.

Switching Node.js Versions with NVM on macOS Executors