Introduction

About this guide

Keeping your Neo4j deployment always up-to-date ensures that you are provided with the latest improvements in performance, security, and bug fixes.

Who should read this?

This upgrade and migration guide is written for experienced system administrators and operations engineers who want to upgrade or migrate self-managed Neo4j deployments.

If you are using Neo4j Aura, you do not need to upgrade or migrate, as the service is always up-to-date. However, if you want to move from Aura 4.4 to 5, from self-managed Neo4j to Aura, or from Aura Free to another plan, you can refer to the following tutorials:

This page introduces some important Neo4j concepts before referring to the version-specific pages.

Preparation

Preparation is key to any successful upgrade or migration. Before making changes to a production DBMS, it is highly recommended to use a test environment to check:

The upgrade/migration process.
Compatibility with other systems.

Version numbers

From January 2025 Neo4j Server adopted calendar versioning (CalVer). Earlier versions, such as Neo4j 4 and 5 used semantic versioning (SemVer). Neo4j’s fully managed cloud service Neo4j Aura uses only the latest version.

Calendar versioning - 2025.01 onwards

The CalVer versioning format, YYYY.MM.PATCH, is based on the year and month of the release, for example, 2025.01, 2025.02, and so on. The patch number is incremented for each release within the same month.

A CalVer may optionally have a fourth component, LTS. This marks the release as a Long-Term Support (LTS) release. There is a new LTS version of Neo4j roughly every 18 to 24 months. LTS releases have a three-year support window during which they receive critical patches and security updates but not new features or improvements.

In the release immediately after an LTS, some deprecated features may be removed, software requirements and the default configuration may change. So care must be taken when upgrading between versions that span an LTS release. LTS release are treated as checkpoints and during upgrades Neo4j server must be upgraded to each LTS version/checkpoint between the current and the desired version.

Neo4j 4 and 5 versioning

Neo4j versions 4 and 5 use semantic versioning (SemVer). Neo4j version numbers are in the pattern MAJOR.MINOR.PATCH.

MAJOR versions introduce significant architectural improvements and features. They are not compatible with previous MAJOR versions. Systems that interact with the database may require updating.
MINOR versions introduce improvements and new features. They are backward compatible with other MINOR versions of the MAJOR version.
PATCH versions fix critical bugs and security issues. They are backward compatible and replace previous releases of the same MAJOR.MINOR version.

Neo4j 4.4 and 5.26 are designated as LTS releases. LTS releases have a three-year support window during which they receive critical patches and security updates but not new features or improvements. Neo4j 4.4 will be supported until November 2025 and Neo4j 5 until November 2028.

Downtime

When configured as a cluster, Neo4j can be upgraded without downtime, with the exception of Neo4j 4.4 to Neo4j 5. Online upgrades from Neo4j 5 LTS to Neo4j 2025.x are supported.

Standalone Neo4j always requires downtime to upgrade.

Servers are upgraded by updating their binaries and restarting. When you move from Neo4j 4.4 to Neo4j 5, you must migrate the databases from the old server to the new server.

Store format

Store format updates are optional unless you are moving to a version that removes support for your old store format. For more information on the available store formats per Neo4j version, see the Operations Manual → Store formats.

There are no changes to store formats between Neo4j 4.4 and 2025.x. However, block format, introduced is Neo4j 5.16, is the preferred store format for Enterprise Edition. High_limit and standard have been deprecated and are scheduled to be removed after 2026.LTS.

Downgrades

Neo4j does not support downgrades. If the upgrade or migration is not successful, you have to do a full rollback, including restoring a pre-upgrade or a pre-migration backup.

Continue reading

If you are on Neo4j 2025 or want to migrate your databases from 5, you can proceed to the Neo4j 2025 section.

If you are on Neo4j 5 or want to migrate your databases from 4.4, you can proceed to the Neo4j 5 section.

If you are upgrading to a version of Neo4j 4, read the Neo4j 4 section.