Upgrade from older versions

This page contains the list of new features and breaking changes of the driver from version 4.4 to 5.x. For a full list of changes, see the Driver → Changelog.

The Neo4j Drivers Migration Assistent simplifies the upgrade process by contextualizing the changelog to your application. It scans your codebase for usage of deprecations and removals, and brings them up to you. The tool doesn’t automatically rewrite your code; it only points at where action is needed, providing in-context information on how each hit should be addressed.

The latest driver version of the 5.x series (5.27) is compatible with Neo4j server both 4.4 and 5.x, so you can upgrade the driver before you upgrade the server. At the same time, the driver version 4.4 is forward compatible with Neo4j server 5.x, so you could also upgrade the server before the driver; however, given that it’s easier to roll back an application upgrade than a server upgrade, it’s recommended to start with the driver.

When upgrading the Neo4j server to a newer version, the Cypher queries in your application may also need updating. The Drivers Migration Assistent doesn’t cover Cypher changes.
See Cypher → Deprecations, additions, and compatibility.

Using the migration assistant, the recommended upgrade steps are:

  1. Set up the environment for the assistant to work in. Download the Drivers Migration Assistant zip, extract it, and locate yourself in its directory. Then, assuming python3 and pip3 are already installed,

    python3 -m venv virtualenvs/neo4j-migration
source virtualenvs/neo4j-migration/bin/activate
pip3 install -r requirements.txt

  2. Run the migration assistant with its default configuration and address all the issues that it surfaces. The path argument supports globbing, and can be repeated.

    python3 main.py -l python /path/*.py /path-recursive/**/*.py

  3. Re-run the assistant with the regex parser and check if any more legit issues are raised.

    python3 main.py -l python --regex-parser /path/*.py /path-recursive/**/*.py

    The regex parser can detect implicit function calls and other hard-to-parse expressions, but is likely to surface more false positives (for more information, see Neo4j Drivers Migration Assistant → Accuracy). You can add any spurious entry to the ignored list, so that the assistant won’t bring them up in future runs.

  4. Although the assistant can detect most of the locations where action is needed, a few changelog entries can’t be surfaced in this form, so you should still revise the breaking changes section and audit your codebase for the changes marked with in the table.

  5. You are ready to upgrade the driver package to the new version. For example, using pip:

    pip3 install -U neo4j==5.27

New features

Support for Python 3.13

The driver is compatible with any Python version starting from 3.7 up to 3.13.
asyncio support

For using the driver’s features asynchronously via the asyncio package.

See Run concurrent transactions.
Driver.execute_query() to run transactions with less knowledge of driver’s internals

The new function is a wrapper for Session.execute_read/write(), but it abstracts away the result processing part and returns a list of records to the caller directly.

See Query the database.
Rust extension for performance

The Rust extension to the Python driver is an alternative driver package that can yield a speedup up to 10x compared to the pure-Python driver.

You can install it with pip install neo4j-rust-ext, either alongside the neo4j package or as a replacement to it. Usage-wise, the drivers are identical.
Export to Pandas Dataframe

Result.to_df() allows for exporting a Result object into a Pandas DataFrame.

See Manipulate query results → Transform to Pandas Dataframe.
Type hints for all public APIs

All public objects have type annotations via the typing package. For (optional) use with type checkers and linters.
Re-authentication

Allows for rotating authentication tokens as well as session-scoped and query-scoped authentication.
Mutual TLS (mTLS) as second authentication factor (2FA)

Allows for configuring client side TLS certificates to authenticate against the server.

See Mutual TLS.
BookmarkManager support

Bookmark managers make it easier to achieve causal chaining of sessions.

See Coordinate parallel transactions.
Notification filtering API

Filtering allows to receive only a subset of notifications from the server, and to improve performance server-side.

See Explore the query execution summary → Filter notifications.
GQL statuses of queries in the ResultSummary

A new property ResultSummary.gql_status_objects is available. It contains a sequence of GqlStatusObjects, containing information about the execution of the query.

This API is planned to supersede the current notifications API.

See Explore the query execution summary → Notifications.
More convenient handling of server-side warnings and notifications

The new sub-logger neo4j.notifications logs every notification raised by the server. The log-level is determined by the notification’s severity.

If logging is not configured explicitly, the default behavior is for warnings to be logged to stderr via warning.warn(). The result of this change is that warnings (such as deprecations) received from the DBMS will appear on stderr.

See Convenient DBMS notifications.
Telemetry

The driver sends anonymous API usage statistics to the server. Use the driver configuration telemetry_disabled=True to opt out.
Concurrency misuse checks

For local development, run your application with python -X dev …​ or set the environment variable PYTHONNEO4JDEBUG to anything non-empty to get additional concurrency misuse checks. Some driver primitives (e.g. sessions) are not safe to be used concurrently, and using them so will lead to hard-to-debug errors. This feature helps identifying such code paths (detection is still inherently racy, hence not guaranteed to always work).

Breaking changes and deprecations

The column Assistant denotes whether the Neo4j Drivers Migration Assistant can detect issues related to the given changelog entry. Entries with a cross mark require manual inspection.

Deprecated features are likely to be removed in version 6.

Version Message Status Assistant

5.0

Dropped support for Python 3.6.

Removed

5.0

Driver — The config options update_routing_table_timeout and session_connection_timeout have been removed. Regular keep-alives are sufficient to avoid the driver getting stuck. Further liveness check config options are available but normally not needed (keep_alive, liveness_check_timeout).

Removed

5.0

Result, Session, and Transaction can no longer be imported from neo4j.work. Import them from neo4j instead.

Removed

5.0

ServerInfo — ResultSummary.server.version_info has been removed. Use ResultSummary.server.agent, ResultSummary.server.protocol_version, or call the dbms.components Cypher procedure instead.

Removed

5.0

Duration — The constructor does not accept subseconds anymore. Use milliseconds, microseconds, or nanoseconds instead.

Removed

5.0

Duration — The property subseconds has been removed. Use nanoseconds instead.

Removed

5.0

Duration — The property hours_minutes_seconds has been removed. Use hours_minutes_seconds_nanoseconds instead.

Removed

5.0

DateTime — The property hour_minute_second has been removed. Use hour_minute_second_nanosecond instead.

Removed

5.0

DateTime — The property second returns an int instead of a float. Use nanosecond to get the sub-second information.

Changed

5.0

All math operations on DateTime objects are element-wise on (months, days, nanoseconds). This changes the working of //, %, /, and *.
Years are equal to 12 months. Weeks are equal to 7 days.
Seconds, milliseconds, microseconds, and nanoseconds are implicitly converted to nanoseconds or seconds as fit.
Multiplication and division allow for floats but will always result in integer values (round to nearest even).

Changed

5.0

Time — The constructor does not accept floats for second anymore. Use nanosecond instead.

Removed

5.0

Time — The property second returns an int instead of a float. Use nanosecond to get the sub-second information.

Changed

5.0

Time — The ticks property’s type changed from float to int. It’s now nanoseconds since midnight instead of seconds.

Changed

5.0

Time — The property ticks_ns has been renamed to ticks.

Removed

5.0

Time — The property hour_minute_second has been removed. Use hour_minute_second_nanosecond instead.

Removed

5.0

Session — Methods .read_transaction() and .write_transaction() are deprecated in favor of .execute_read() and .execute_write(). Through the new methods, the first argument of transaction functions is a ManagedTransaction object. It behaves like a regular Transaction object, except it does not offer the .commit(), .rollback(), .close(), and .closed() methods.

Deprecated

5.3

Package-alias neo4j-driver is deprecated. It will stop receiving updates starting with 6.0.0. Install neo4j instead.

Deprecated

5.0

Node, Relationship — Property id (int) is deprecated in favor of element_id (str). This also affects Graph objects, as indexing graph.nodes[…​] and graph.relationships[…​] with integers is deprecated in favor of indexing them with strings.

Deprecated

property
indexing

5.0

Implicit closing of drivers and sessions through __del__() (destructor) is deprecated. This behaviour is non-deterministic as there is no guarantee that the destructor will ever be called. A ResourceWarning is emitted instead.
Call driver.close() explicitly or create the driver via a with statement.

Deprecated

5.0

Import of the following modules is deprecated without replacement, as they are internal and should not be used by client code: neo4j.packstream, neo4j.routing, neo4j.config, neo4j.meta, neo4j.data.

ExperimentalWarning (previously in meta) should be imported directly from neo4j.
neo4j.meta.version is exposed through neo4j.__version__.

Deprecated

5.0

Driver — The config option trust is deprecated. New options trusted_certificates and ssl_context are available.

Deprecated

5.0

Session — The method .last_bookmark() is deprecated in favor of .last_bookmarks(). The logic is similar, but the new method returns neo4j.Bookmarks instead of str.

Deprecated

5.0

neo4j.Bookmark is deprecated in favor of neo4j.Bookmarks.

Deprecated

5.0

Importing submodules from neo4j.time is deprecated. Import everything from neo4j.time directly instead.

Deprecated

5.7

Importing neo4j.work and its submodules is deprecated. Import everything from neo4j directly instead.

Deprecated

5.0

The following objects are deprecated without replacement, as they are internal and should not be used by client code: neo4j.spatial.hydrate_point, neo4j.spatial.dehydrate_point, neoj4.Config, neoj4.PoolConfig, neoj4.SessionConfig, neoj4.WorkspaceConfig, neo4j.data.DataDehydrator, neo4j.data.DataHydrator.

Deprecated

5.22

Class SummaryNotificationPosition is deprecated in favor of SummaryInputPosition.

Deprecated

5.0

Undocumented methods Neo4jError.is_fatal_during_discovery() and Neo4jError.invalidates_all_connections() are deprecated without replacement.

Deprecated

5.26

Undocumented method Neo4jError.hydrate() is deprecated without replacement.
Altering the attributes of a Neo4jError is deprecated.

Deprecated