Skip to content

Node.js Installation Guide

Jump to bottom
Julien Von Der Marck edited this page Jan 13, 2026 · 1 revision

Node.js 20+ Installation Guide for Next.js App

This guide covers how to install Node.js 20 (or greater) on macOS, Windows, and Linux. We'll focus on using NVM (Node Version Manager) which allows you to easily manage multiple Node.js versions.

Table of Contents

Why Use NVM?

NVM (Node Version Manager) is highly recommended because it:

  • ✅ Allows you to install and switch between multiple Node.js versions
  • ✅ Avoids permission issues with global npm packages
  • ✅ Makes it easy to match the exact Node version required by different projects
  • ✅ Simplifies Node.js upgrades and downgrades
  • ✅ Keeps your system clean and organized

Prerequisites

Required Node.js Version: Node.js 20 or greater

You can verify this requirement in the project's package.json:

{
  "engines":  {
    "node": ">=20.0.0"
  }
}

macOS Installation

Installing NVM on macOS

  1. Install NVM using the install script:

    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

    Or using wget:

    wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install. sh | bash

  2. Add NVM to your shell profile:

    For Zsh (default on macOS Catalina and later):

    # Add to ~/. zshrc
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \.  "$NVM_DIR/bash_completion"

    For Bash:

    # Add to ~/.bash_profile or ~/.bashrc
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \.  "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

  3. Reload your shell configuration:

    source ~/.zshrc  # or source ~/.bash_profile

  4. Verify NVM installation:

    nvm --version

Alternative: Homebrew (Not Recommended for NVM)

While you can install Node.js directly with Homebrew, using NVM is preferred for version management:

# Direct installation (not recommended if you want version management)
brew install node@20

Windows Installation

Installing NVM on Windows

Windows uses a different tool called nvm-windows (not the same as the macOS/Linux version).

  1. Download nvm-windows:

  2. Run the installer:

    • Double-click nvm-setup.exe
    • Follow the installation wizard
    • Choose installation directory (default is fine)
    • Choose the symlink path for Node.js

  3. Verify installation: Open Command Prompt or PowerShell and run:

    nvm version

Alternative: WSL (Windows Subsystem for Linux)

If you're using WSL, follow the Linux installation instructions below.

Linux Installation

Installing NVM on Linux

  1. Install NVM using the install script:

    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

    Or using wget:

    wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

  2. Add NVM to your shell profile:

    # The installer usually adds this automatically to ~/.bashrc or ~/.zshrc
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \.  "$NVM_DIR/bash_completion"

  3. Reload your shell configuration:

    source ~/.bashrc  # or source ~/.zshrc

  4. Verify NVM installation:

    nvm --version

Installing Node.js with NVM

Once NVM is installed, follow these steps on any platform:

Install Node.js 20 (or Latest LTS)

# Install Node.js version 20 (latest v20.x)
nvm install 20

# Or install the latest LTS (Long Term Support) version
nvm install --lts

# Or install a specific version
nvm install 20.11.0

Set Default Node Version

# Use Node.js 20
nvm use 20

# Set Node.js 20 as the default version
nvm alias default 20

Verify Node.js Installation

# Check Node.js version
node -v
# Should output:  v20.x.x (or higher)

# Check npm version
npm -v
# Should output: 10.x.x (or higher)

Setting Up the Next.js App

Now that Node.js 20+ is installed, you can set up the Next.js application:

1. Clone or Download the Project

# If using git
git clone <repository-url>
cd <project-directory>

# Or if you downloaded a ZIP, extract and navigate to the folder

2. Install Dependencies

npm install

This will install all required packages from package.json.

3. Run the Development Server

npm run dev

The Next.js app should now be running at http://localhost:3000

4. Build for Production (Optional)

# Create an optimized production build
npm run build

# Start the production server
npm start

Verifying Installation

Check Node.js and npm

node -v    # Should show v20.x.x or higher
npm -v     # Should show npm version

Check Next.js Project

# In your project directory
npm run dev

Visit http://localhost:3000 in your browser.

Managing Multiple Node Versions

List Installed Versions

# List installed Node versions
nvm ls

# List all available Node versions (macOS/Linux)
nvm ls-remote

# List all available Node versions (Windows)
nvm list available

Switch Between Versions

# Switch to Node. js 20
nvm use 20

# Switch to Node.js 18
nvm use 18

# Switch to latest LTS
nvm use --lts

Uninstall a Version

# Uninstall Node.js 18
nvm uninstall 18

Using . nvmrc (macOS/Linux/WSL)

Create a .nvmrc file in your project root to specify the required Node version:

echo "20" > .nvmrc

Then anyone can automatically use the correct version:

nvm use
# Automatically uses the version specified in .nvmrc

Troubleshooting

"nvm: command not found"

macOS/Linux:

  • Ensure NVM is added to your shell profile (.zshrc, .bashrc, .bash_profile)
  • Restart your terminal or run source ~/.zshrc

Windows:

  • Restart Command Prompt or PowerShell with Administrator privileges
  • Ensure nvm-windows installed correctly

"node: command not found" after installing

# Make sure you've activated a Node version
nvm use 20

# Set a default version
nvm alias default 20

Permission errors with npm

NVM automatically handles permissions, but if you encounter issues:

# Never use sudo with npm when using NVM
# Instead, reinstall the package without sudo
npm install <package-name>

Next.js won't start

  1. Check Node version:

    node -v  # Must be 20 or higher

  2. Clear npm cache and reinstall:

    npm cache clean --force
rm -rf node_modules package-lock.json
npm install

  3. Check for port conflicts:

    # If port 3000 is in use, specify a different port
npm run dev -- -p 3001

Additional Resources

Quick Reference

# Install Node.js 20
nvm install 20

# Use Node.js 20
nvm use 20

# Set default version
nvm alias default 20

# Verify installation
node -v && npm -v

# Install project dependencies
npm install

# Run development server
npm run dev

# Build for production
npm run build && npm start

Summary

  1. ✅ Install NVM (Node Version Manager)
  2. ✅ Install Node.js 20 or greater using NVM
  3. ✅ Navigate to your Next.js project directory
  4. ✅ Run npm install to install dependencies
  5. ✅ Run npm run dev to start the development server
  6. ✅ Open http://localhost:3000 in your browser

You're now ready to develop and run the Next.js application! 🚀

📦 Installation Guides

Clone this wiki locally