Installing Node.js

This guide covers installing Node.js on Windows, macOS, and Linux. Desktop and the Microsoft Store edition no longer bundle Node.js; they use the node and npm on your system directly, and OpenSpec and most Agent CLIs depend on it as well.

Version Requirements

Node.js 24 or higher is required, and 24 is also the minimum. In most cases, just install the latest LTS version. npm is installed together with Node.js, so you do not need to install it separately.

Which Installation Methods Need It

• Microsoft Store / Desktop: Required, and node and npm must be found on the system PATH.
• Docker Compose: Not needed on the host.

Installing Node.js

Windows

Method One: Official Installer (Recommended)

1. Visit the Node.js Official Website
2. Download the LTS (Long Term Support) version Windows installer (.msi file), and confirm the version is not lower than 24
3. Double-click to run the installer
4. Follow the installation wizard prompts to complete installation:
   • Accept the license agreement
   • Choose installation path (default is fine)
   • Keep “Add to PATH” checked
   • Click “Install” to start installation
5. After installation completes, click “Finish”

Method Two: Using winget

Open PowerShell or Command Prompt and run:

winget install OpenJS.NodeJS.LTS

After installation, reopen the terminal for changes to take effect.

macOS

Method One: Official Installer (Recommended)

1. Visit the Node.js Official Website
2. Download the LTS (Long Term Support) version macOS installer (.pkg file), and confirm the version is not lower than 24
3. Double-click to run the installer
4. Follow the installation wizard prompts to complete installation:
   • Click “Continue”
   • Accept the license agreement
   • Choose installation disk
   • Click “Install” and enter administrator password
5. After installation completes, click “Close”

Method Two: Using Homebrew

If you have Homebrew installed, you can install Node.js via terminal:

brew install node

Homebrew will automatically add Node.js to your PATH. If the command is not available, restart the terminal or run:

eval "$(/opt/homebrew/bin/brew shellenv)"

Ubuntu/Debian

Using NodeSource Repository (Recommended)

The Node.js in the distribution’s own repositories is usually lower than 24, so use the 24.x repository provided by NodeSource:

# Use curl to download the installation script
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs

Do not install the distribution’s bundled version directly with sudo apt-get install nodejs npm; it most likely does not meet the minimum requirement of 24.

If you do not want to add a third-party package source, you can also use nvm or fnm described below.

CentOS/RHEL

Using NodeSource Repository (Recommended)

# Use curl to download the installation script
curl -fsSL https://rpm.nodesource.com/setup_24.x | sudo bash -
sudo yum install -y nodejs

The Node.js in the distribution’s own repositories is usually lower than 24, so installing it directly is not recommended. You can also use nvm or fnm described below instead.

Fedora

Using dnf Package Manager

sudo dnf install -y nodejs npm

After installation, run node --version to confirm the version is not lower than 24. If the version in the repository is lower, use the NodeSource 24.x repository instead, or use nvm or fnm described below.

Using Version Management Tools

If you need to switch between multiple Node.js versions, you can use version management tools.

Note for Desktop Users

On macOS and Linux, tools such as nvm and fnm usually set PATH only in shell configuration files (such as .bashrc and .zshrc). Desktop launched from the Dock, the application menu, or a desktop icon does not read those files and may not find node. If you use a version management tool, launch Desktop from a terminal where node already works, or use the system-wide installation methods above instead.

nvm (Node Version Manager)

Installing nvm

Linux/macOS

Copy the latest installation command directly from the nvm official repository README; do not use old installation script URLs.

After installation, reload your shell configuration:

source ~/.bashrc
# Or for Zsh users
source ~/.zshrc

Windows

On Windows, we recommend using nvm-windows:

1. Download the latest nvm-setup.exe from nvm-windows releases
2. Run the installer
3. Reopen Command Prompt or PowerShell

Using nvm

After installing nvm, you can use it to install and manage Node.js versions:

# Install Node.js 24
nvm install 24

# Switch to Node.js 24
nvm use 24

# Set default version
nvm alias default 24

# List installed versions
nvm list

The alias command is not available in nvm-windows; just use nvm install 24 and nvm use 24.

fnm (Fast Node Manager)

fnm is a faster and simpler Node.js version management tool built with Rust.

Installing fnm

Linux/macOS

# Install using curl
curl -fsSL https://fnm.vercel.app/install | bash

# After installation, reload shell configuration
source ~/.bashrc
# Or for Zsh users
source ~/.zshrc

Windows

Use scoop or winget:

# Use scoop
scoop install fnm

# Or use winget
winget install Schniz.fnm

Using fnm

# Install Node.js 24
fnm install 24

# Switch to Node.js 24
fnm use 24

# Set default version
fnm default 24

# List installed versions
fnm list

Acceleration for Mainland China Users

If you are in Mainland China, downloading Node.js and npm packages may be slow. You can use domestic mirrors.

npm Mirror

# Temporarily use the mirror to install
npm install --registry=https://registry.npmmirror.com

# Permanently set the mirror
npm config set registry https://registry.npmmirror.com

# Verify the mirror is set successfully
npm config get registry

Node.js Installer Mirror

Node.js installers also have a mirror download address: https://npmmirror.com/mirrors/node/. After visiting it, choose a version not lower than 24 to download.

Homebrew Mirror

If you use Homebrew in Mainland China, you can configure the USTC mirror for bottles:

export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.ustc.edu.cn/homebrew-bottles

Verifying Installation

After installation, verify that Node.js and npm are available in a newly opened terminal:

# Check the Node.js version, v24.0.0 or higher is required
node --version

# Check the npm version
npm --version

Successful output should look like:

$ node --version
v24.3.0

$ npm --version
11.4.2

If node --version shows a version lower than 24, reinstall using the methods above, or use a version management tool to switch to 24 or higher.

Configuring the npm Global Directory

Desktop installs managed packages such as Agent CLIs into your local npm global directory. If the global directory is in a location that requires administrator privileges, you may see an EACCES permission error during installation. It is recommended to move the global directory into your user directory instead of changing the permissions of system directories:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global

Then add ~/.npm-global/bin (on Windows, the npm global directory itself) to the system PATH, and restart your terminal and Desktop. When you use nvm or fnm, the global directory is already under your user directory, so this step is not needed.

Troubleshooting

Windows Issues

Command Not Available

If the node or npm command is not available after installation:

1. Restart Command Prompt or PowerShell
2. If still not available, manually add Node.js to PATH:
   • Search for “Environment Variables” and open “Edit system environment variables”
   • Click “Environment Variables”
   • Find “Path” in “System variables” and click “Edit”
   • Add Node.js installation path (default: C:\Program Files\nodejs\)
   • Click “OK” to save changes
3. Fully quit and restart Desktop

PowerShell Execution Policy

If you encounter execution policy errors when using nvm or npm scripts:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

macOS Issues

Permission Errors

If you encounter permission errors when installing global npm packages, see Configuring the npm Global Directory above, or use nvm / fnm instead.

Command Not Available

If the command is not available after installation, restart the terminal and confirm that the directory containing Node.js (usually /usr/local/bin or /opt/homebrew/bin) is in PATH.

Linux Issues

Permission Errors

If you encounter permission errors when installing global npm packages, see Configuring the npm Global Directory above, or use nvm / fnm instead of installing global packages with sudo.

Version Too Old

If the Node.js version installed via the system package manager is lower than 24:

1. Use the NodeSource 24.x repository (see above)
2. Or use a version management tool (nvm / fnm)

Checking Environment

If verification fails, check the following:

Windows

# Check if Node.js is in PATH
where node

# Check installation path
Get-Command node

macOS

# Check if Node.js is in PATH
which node

# Check installation path
ls -l $(which node)

Linux

# Check if Node.js is in PATH
which node

# Check installation path
ls -l $(which node)

Next Steps

After Node.js installation is complete, you can continue with the following steps:

Return to Installation GuideContinue with prerequisites such as Git, and choose the installation method that fits you.

Introduction to OpenSpecGo to the standalone OpenSpec documentation site to learn about installation, core concepts, and the specification-driven workflow.

Install AI Agent CLISee the official installation entries for the currently supported Agent CLIs, and tell one-click installation apart from manual installation / authentication.

Need More Help?

If you encounter issues not covered here:

1. Visit the Node.js Official Documentation
2. See How Desktop Uses Your Node Environment
3. Review the HagiCode Product Overview for current product and tooling context