Upgrading your Next.js application to newer versions helps you access the latest features, performance improvements, and security updates. Next.js provides built-in commands and automated transformation scripts (called codemods) to update your packages, adjust configuration settings, and rewrite deprecated code safely with minimal manual effort.
You can perform upgrades using interactive commands in your terminal, via automated prompts during development or builds, or by using specialized upgrade options tailored for coding agents.
Command Line Upgrades
Running Terminal Upgrades
This section covers how to run upgrades manually from your terminal and manage target version options.
Open your terminal and navigate to your project directory.
Run the upgrade command, optionally specifying a target revision or upgrade type:
npx @next/codemod upgrade [revision]
If no revision is provided, the tool defaults to the minor upgrade type.
Review any interactive prompts in your terminal to choose whether to update related dependencies (such as React or ESLint) or apply automated code transformations.
Note
If you are running in a non-interactive environment (such as a CI pipeline or automated script), the upgrade tool automatically runs in non-interactive mode and accepts default choices for all prompts.
Available Upgrade Revisions
When specifying a target revision, you can use semantic upgrade types, NPM distribution tags, or exact version numbers.
Revision Option
Description
patch
Updates to the latest patch within the current minor version (e.g., 15.0.x to 15.0.y).
minor
Updates to the latest minor version within the current major version (e.g., 15.0.x to 15.1.x).
major
Updates to the latest stable version (equivalent to latest).
Distribution tags
Target a specific distribution channel: latest, canary, rc, or beta.
Exact versions
Provide a precise version number (e.g., 15.0.0).
Important
Supported upgrade types and distribution tags: patch, minor, major, latest, canary, rc, beta.
Sources: packages/next-codemod/bin/upgrade.ts, packages/next/src/bin/next.ts
Upgrade Command Options
You can customize the behavior of the upgrade command using various flags and options.
CLI Flag
Description
--revision <revision>
Specifies the target Next.js version using a dist tag or exact version number.
--verbose
Outputs detailed diagnostic information during the upgrade process.
-y, --yes
Skips all interactive prompts and accepts default values automatically.
--skip-adoption
Skips optional feature-adoption codemods while applying version migrations.
--skip-react-upgrade
Keeps React dependencies, types, and overrides unchanged and skips React codemods.
--skip-eslint-upgrade
Keeps ESLint dependencies unchanged and skips the ESLint migration codemod.
--agent [type]
Upgrades using an automated policy type (security, latest, or experimental-future).
Warning
Always ensure your working directory and Git status are clean (committed or stashed) before running an upgrade, as automated scripts will modify your project files.
Automated Upgrade Nudges and Prompts
Next.js can automatically assess your project's version during development (next dev) or production builds (next build) and notify you if a security vulnerability or newer version is available.
When an upgrade nudge appears, you can choose to apply the update immediately or dismiss the reminder for the current session. Upgrade policies can be configured to target specific channels:
