---
title: "Migration Guides — Overview"
aliases: [payload-migration, payload-upgrade, payload-breaking-changes]
tags: [payloadcms, migration, upgrade, versioning]
sources: [raw/migration-guide__overview.md]
created: 2026-05-15
updated: 2026-05-15
---

# Migration Guides — Overview

Payload follows [semantic versioning](https://semver.org/). Major version bumps may include breaking changes; each upgrade path has a dedicated migration guide.

## Upgrade Paths

| From | To | Guide |
|------|----|-------|
| Payload 2.x | 3.0 | [[wiki/payloadcms/migration-troubleshooting\|Migration & Troubleshooting]] — v2→v3 section |
| Payload 3.x | 4.0 | [[wiki/payloadcms/migration-troubleshooting\|Migration & Troubleshooting]] — v3→v4 section |

## Key Takeaways

- Payload uses **semantic versioning** — minor/patch releases are safe to upgrade; only major bumps may break.
- Always read the migration guide for the specific major version before upgrading.
- Two active upgrade paths exist: **2→3** and **3→4**.
- See [[wiki/payloadcms/database-migrations\|Database Migrations]] for running DB schema migrations after a Payload upgrade.
- See [[wiki/payloadcms/installation\|Installation]] for version requirements (Node 24+, Next.js 16.2.6+).

## Related

- [[wiki/payloadcms/migration-troubleshooting\|Migration & Troubleshooting]] — full codemod steps, dependency dedup fix, common errors
- [[wiki/payloadcms/database-migrations\|Database Migrations]] — `migrate`, `migrate:create`, `migrate:rollback` CLI reference
- [[wiki/payloadcms/getting-started\|Getting Started]] — fresh install baseline

---

*Source: raw/migration-guide__overview.md — https://payloadcms.com/docs/migration-guide/overview*
