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.

Neo4j server versioning

The Calendar versioning (CalVer) 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.

Cypher versions

As of Neo4j 2025.06, the Cypher^® language is decoupled from the Neo4j server and follows its own versioning. You can choose between Cypher 5 and Cypher 25.

You can specify the version of Cypher by configuring a default Cypher version for the whole DBMS, per database, or by setting it on a per-query basis.

Setting the default language to CYPHER 5 ensures that all queries run on that database will use the version of Cypher 5 as it existed at the time of the Neo4j 2025.06 release (unless you prepend your queries with CYPHER 25, which overrides this default). Any changes introduced after the 2025.06 release will not affect the semantics of the query.

Setting the default language to CYPHER 25 ensures that all queries run on that database will use the version of Cypher 25 that the database is currently running (unless you prepend your queries with CYPHER 5, which overrides this default). For example, a Neo4j 2025.08 database with default language Cypher 25 will use Cypher 25 as it exists in Neo4j 2025.08, including any changes introduced in Neo4j 2025.06, 2025.07, and 2025.08.

For more information, see the Operations Manual → Configure the Cypher default version and Cypher Manual → Select Cypher version.

The following table outlines which Cypher version is assigned to databases in different upgrade or installation scenarios, when not explicitly set on the DBMS level (using db.query.default_language):

Table 1. Default Cypher version per scenario
Scenario	Existing databases	New databases
New installation	N/A	Defaults to Cypher 5
Upgrades	Cypher 5	Defaults to Cypher 5
Upgrades	Cypher 25	Defaults to Cypher 5

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.