---
title: "Upgrading Next.js Versions"
description: "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 transform..."
last_updated: "2026-10-12T06:40:49.127572+00:00"
canonical_url: "https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/guide/configuration/upgrading-next-js-versions"
---

## Overview

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.

1. Open your terminal and navigate to your project directory.
2. Run the upgrade command, optionally specifying a target revision or upgrade type:
   ```bash
   npx @next/codemod upgrade [revision]
   ```
   If no revision is provided, the tool defaults to the `minor` upgrade type.
3. 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.

```mermaid
flowchart TD
    A[Start dev or build] --> B{Assessment Check}
    B -- Vulnerability or Update Found --> C[Show Upgrade Menu / Nudge]
    C --> D{User Choice}
    D -- Update --> E[Run Automated Upgrade]
    D -- Dismiss / Skip --> F[Continue Normal Execution]
```

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:

* Supported agent policies: `security`, `latest`, `experimental-future`
* Sources: `packages/next/src/lib/upgrade/nudge.ts`, `packages/bin/next.ts`

> [!TIP]
> If a security vulnerability is detected in your installed version, you can invoke an automated security upgrade directly by running:
> ```bash
> npx next upgrade --agent=security
> ```

## Related

- [Environment and Settings](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/guide/configuration/environment-and-settings)


## Sitemap

See the full [sitemap](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/llms.txt) for all pages in this wiki.