How to Install Next.js on Windows, Mac, and Linux

Section 01 · What it is

What is Next.js, in one paragraph

Before you install something, it helps to know what it is and why people pick it over plain React.

Quick answer

What is Next.js? Next.js is a React framework. You still write React components, but Next gives you a folder based routing system, server side rendering, image optimisation, API routes, a smart build pipeline, and zero configuration TypeScript. It is the default choice for new React apps and is what Vercel and the React team recommend on react.dev.

Plain React is a library for building user interfaces. It does not tell you how to handle routing, how to split your bundle, how to fetch data on the server, or how to deploy. You either bolt on tools yourself or you reach for a framework. Next.js is by far the most popular framework, and the React team officially recommends it in the start a new React project guide.

What you get on day one with Next.js: routing based on the folder structure, server components that run on the server and ship zero JavaScript to the browser, automatic code splitting, image and font optimisation, and a single command that builds for production. You can ignore most of it on your first day and just write components like you would in plain React.

Section 02 · Prerequisites

What you need before you install Next.js

There is exactly one prerequisite. Get this right and the rest is mechanical.

The one thing you must have

Node.js, version 18.18 or newer. Next.js 14 and 15 will not run on older Node. Everything else (a code editor, a terminal, a browser) you almost certainly have already.

Open your terminal and check whether Node is installed:

bash

node --version
# expected: v18.18.0 or newer, ideally v20 or v22

npm --version
# expected: 10.x or newer

If you see a version number that starts with 16 or 17, your Node is too old. If you see "command not found", Node is missing entirely. The next section walks through installing or upgrading Node on each operating system. Once Node is right, the actual Next.js install is the same one liner everywhere.

Three step flow showing install Node, run create-next-app, then npm run dev. — Three steps from a blank machine to a running Next.js app on localhost:3000.

Section 03 · Windows

Install Next.js on Windows

The smooth path on Windows uses the official Node installer, not Chocolatey or Scoop.

Go to nodejs.org and download the LTS installer for Windows.
Run the installer. Accept defaults. Leave the "Automatically install the necessary tools" checkbox on if it appears (it pulls Python and the build tools you may need later for native modules).
Close every terminal window that was open before the install. Open a fresh PowerShell or Windows Terminal so it picks up the new PATH.
Verify Node is on the path:

powershell

node --version
npm --version

Now install Next.js. Pick a folder you do not mind cluttering (your Documents or a dedicated dev folder works) and run:

powershell

npx create-next-app@latest my-first-app
cd my-first-app
npm run dev

Open http://localhost:3000 in your browser. You should see the default Next.js welcome page.

PowerShell execution policy error

If PowerShell complains 'running scripts is disabled on this system' when you run npx, fix it once with: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned. This is a common first day Windows headache and the only one you typically hit.

Section 04 · macOS

Install Next.js on macOS

On a Mac, Homebrew plus Node Version Manager is the cleanest setup. It also lets you switch Node versions per project later.

If you do not already have Homebrew, install it first:

bash

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Then install Node. The simplest path is to install it directly with brew:

bash

brew install node@20

# verify
node --version
npm --version

If you expect to work on more than one Node project over time, install nvm instead. It lets you keep multiple Node versions side by side and switch with one command. Either works for installing Next.js today.

Now install Next.js itself:

bash

cd ~/Developer            # or wherever you keep projects
npx create-next-app@latest my-first-app
cd my-first-app
npm run dev

Open http://localhost:3000. You should see the welcome screen. If the terminal stays stuck on "Starting…" for more than ten seconds, check that another process is not already using port 3000 with lsof -i :3000.

Section 05 · Linux

Install Next.js on Linux

On Ubuntu, Debian, Fedora, and Arch the recommended path is NodeSource's official Node binary, not the distro package which is usually two major versions behind.

Ubuntu and Debian:

bash

# Install Node 20 from NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# verify
node --version
npm --version

Fedora and RHEL:

bash

curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo dnf install -y nodejs

node --version

Arch and Manjaro:

bash

sudo pacman -S nodejs npm
node --version

Once Node is healthy, the Next.js install command is the same as on Windows and macOS:

bash

npx create-next-app@latest my-first-app
cd my-first-app
npm run dev

Permission errors on Linux

If npm warns about EACCES on global installs, do not fix it by running npm with sudo. Instead, set npm to use a folder you own: mkdir ~/.npm-global, then npm config set prefix ~/.npm-global, then add ~/.npm-global/bin to your PATH. This is the official npm recommended fix.

Section 06 · The prompts

What every create-next-app prompt actually asks

The installer asks seven questions. Pick wrong and you fight the framework later. Here is what to answer and why.

What is your project named?

Whatever you typed after the command. Lowercase, hyphens, no spaces. This becomes the folder name.

Would you like to use TypeScript?

Yes. Modern Next.js tutorials, libraries, and example code assume TypeScript. The cost on day one is almost zero; the payoff over a real project is large.

Would you like to use ESLint?

Yes. ESLint catches the bugs you cannot see and is wired up automatically. There is no upside to skipping it.

Would you like to use Tailwind CSS?

Yes. Tailwind is the de facto styling solution for Next.js apps today. You can ignore it if you prefer plain CSS, but every official template assumes Tailwind.

Would you like your code inside a src/ directory?

Yes for most projects. It keeps your source code separate from config files and is the convention most teams use.

Would you like to use App Router?

Yes, this is the default and recommended choice. App Router replaces the old Pages Router. New tutorials, the official docs, and the React team all assume App Router.

Would you like to customize the default import alias?

No. Keep @/* unless you have a specific reason to change it. Almost every code example you find online uses @/.

When the installer finishes you will see a folder with package.json, a node_modules folder full of dependencies, and an app folder with the starter UI. The next post in this series opens that folder and explains what every file is for.

Section 07 · Troubleshooting

Five errors that hit nine out of ten beginners

Almost every first day Next.js problem falls into one of these buckets. Skim the list before you ask for help.

EACCES or permission denied on npm install

You ran the command from a folder you do not own, or you tried to install globally as root once and now your cache is owned by root. Fix: cd into a folder you own, or run sudo chown -R $(whoami) ~/.npm to fix cache ownership.

The engine 'node' is incompatible with this module

Your Node is too old. Upgrade to Node 20 LTS or newer. Check with node --version. This is the single most common new user error on Linux and on company laptops with locked down Node versions.

Port 3000 is already in use

Something else is using the port. On macOS or Linux: lsof -i :3000 to find the process, then kill -9 <pid>. On Windows: netstat -ano | findstr :3000 then taskkill /PID <pid> /F. Or run next dev with --port 3001.

Module not found: Can't resolve '@/components/...'

You renamed or moved a file but the import path still references the old name. Run npm run dev again after saving; the build cache sometimes lags. If it persists, delete the .next folder and restart.

npm run dev starts then immediately exits

Almost always a syntax error in app/layout.tsx or app/page.tsx that the type checker caught. Scroll up in the terminal output; the real error is usually four or five lines above where you are looking.

Section 08 · Next steps

You shipped a Next.js app. What now?

The welcome page is just a starting point. Three concrete next moves.

Open the folder in your editor and read the next post, Next.js Folder Structure Explained for Beginners. It walks through every file create-next-app generated and what it is for.
Build something tiny. The third post in this series, Build a Calculator in Next.js Step by Step, is a complete hands on project you can finish in under an hour.
When you are ready for user input, the fourth post, Build a Form in Next.js With Server Actions and Zod, shows the modern way to handle form submissions without a separate API route.

If you are evaluating Next.js for something larger than a hobby project (an internal tool, a customer facing app, an agentic AI product) it pays to start with the right architecture. See my agentic AI consulting service for how production grade Next.js apps are scoped and shipped.

Section 09 · Questions

Frequently asked questions

The questions every beginner asks in their first week with Next.js.

Do I need to know React before I install Next.js?

A little. You should be comfortable with components, props, and useState. You do not need advanced React knowledge. If you can build a React counter component, you have enough to start Next.js and learn the rest as you go.

Which Node version should I install?

Node 20 LTS is the sweet spot. Next.js 15 supports Node 18.18 and newer, but Node 20 is the version most production deployments run on and the one libraries test against most heavily.

Is npx create-next-app safe to run?

Yes. npx fetches the official create-next-app package from npm, runs it once to scaffold your project, and removes it. It does not install anything globally. The package is maintained by the Next.js team at Vercel.

Can I install Next.js without npm, using yarn or pnpm?

Yes. The equivalent commands are yarn create next-app or pnpm create next-app. They produce the same starter project. Pick whichever package manager your team uses.

Why does the install take so long?

create-next-app downloads several hundred npm packages including React, the Next.js compiler, TypeScript, Tailwind, and ESLint. On a fast connection this takes one to two minutes. On a slow connection it can take five or more. This is normal; you only pay this cost once per project.