Cross-Platform Node.js Installation and Troubleshooting Guide

Why Use Node.js as an Example

Many command-line tools for AI coding assistants are distributed as npm packages and require the Node.js runtime. Node.js includes two main executables, node and npm, making installation and verification straightforward. This makes it a useful example for setting up development environments across platforms. Once you understand this process, the same general approach applies to other runtimes such as Python and Go.

When choosing a version, follow two principles:

1. Prefer a release in the Active LTS stage. These versions have undergone longer testing, generally offer better compatibility, and continue to receive security updates.
2. Unless a specific tool requires it, avoid versions that are no longer maintained.

Check the release schedule on the official Node.js website to confirm each version’s support status and end date.

Pre-Installation Checks

Confirm the following four items before installation. These checks can prevent most download failures and interrupted installations.

1. System architecture

   On Windows, run:

   systeminfo | findstr /C:"System Type"

   The output should indicate x64 or ARM64. On macOS and Linux, run:

   uname -m

   Common outputs include x86_64, arm64, and aarch64. The architecture must match the installer or package you download.

2. Available disk space

   The installer and global packages may require several hundred megabytes. Reserving at least 2 GB is recommended. On Linux and macOS, check available space with:

   df -h ~

3. Network connectivity

   Run the following command to verify access to the npm registry:

   npm ping

   If the command times out, review the proxy troubleshooting steps relevant to your environment.

4. Back up your PATH

   On Windows, run:

   echo %PATH% > path_backup.txt

   On macOS and Linux, run:

   echo $PATH > ~/path_backup.txt

   Installers sometimes modify the PATH environment variable. A backup makes it easier to compare or restore the previous configuration if problems occur.

Installing and Verifying Node.js on Windows

The recommended approach is to install the LTS release with winget:

winget install OpenJS.NodeJS.LTS

You can also download the LTS .msi installer from the official Node.js website. During setup, leave Add to PATH enabled. Otherwise, the terminal may not be able to invoke node directly.

After installation, close all open terminals. Then open a new PowerShell or Command Prompt window and run:

node -v
npm -v

Both commands should print a version number.

If the system reports that the command cannot be found, troubleshoot in this order:

1. Open a new terminal window. Environment-variable changes only take effect in newly opened shells.

2. In PowerShell, run:

   $env:Path -split ';'

   Check whether the list contains:

   C:\Program Files\nodejs\

   If it does not, add that directory to the user-level Path environment variable manually, then open a new terminal.

PowerShell may also display an error stating that npm.ps1 cannot be loaded because script execution is disabled on the system. This is caused by the PowerShell execution policy. A temporary workaround is to use:

npm.cmd -v

For a persistent change, you can run:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

This modifies a security policy. Confirm that the change complies with your organization’s security requirements before applying it.

If antivirus software blocks the installer, download it again from the official source and verify that its file hash matches the value published by the official website. Then add the installer to the trusted list if appropriate. Do not disable real-time protection simply to complete the installation.

After installation, update npm itself and inspect the globally installed packages:

npm install -g npm@latest
npm ls -g --depth=0

Installing and Verifying Node.js on macOS

If Homebrew is installed, run:

brew install node

To upgrade Node.js later, use:

brew upgrade node

After installation, verify the runtime and npm:

node -v
npm -v

You can also check the executable path:

which node

On Apple Silicon Macs, the path is commonly:

/opt/homebrew/bin/node

On Intel-based Macs, it is commonly:

/usr/local/bin/node

Alternatively, download the official .pkg installer and complete the setup wizard.

Avoid installing both the Homebrew version and the official package version on the same machine unless you understand how PATH resolution works. Otherwise, the terminal may invoke a different version than expected. Use the following command to list all available candidates:

which -a node

Keeping a single installation source is generally the simplest way to avoid conflicts.

macOS permission problems most often occur during global package installation. Running:

sudo npm install -g

can make the global package directory owned by root, causing later installations by a regular user to fail with an EACCES error.

A safer approach is to move the global npm directory into your user account:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc

macOS uses zsh by default, so the configuration is added to ~/.zshrc.

If the ~/.npm directory already contains files created by root, fix their ownership with:

sudo chown -R $(whoami) ~/.npm

Installing and Verifying Node.js on Linux

On Debian and Ubuntu, install Node.js and npm from the system repositories:

sudo apt update
sudo apt install -y nodejs npm

On Fedora and RHEL-based distributions, use:

sudo dnf install nodejs npm

Packages in system repositories are often older than the latest supported releases. After installation, check the version:

node -v

If it is too old for your project, consider using nvm instead.

nvm is useful when you need to switch between Node.js versions for different projects. Copy the current installation command from the official nvm repository, run it, and then reopen your terminal. Next, execute:

nvm install --lts
nvm use --lts
nvm alias default lts/*
node -v

To install and use a specific major version, run:

nvm install <major-version>
nvm use <major-version>

To list all Node.js versions installed through nvm, run:

nvm ls

When a Linux installation fails, the cause is often related to one of three areas. Network proxy problems can be investigated with environment-variable checks such as:

env | grep -