neo4j

library6.2.0pypypi✓ verified 32d ago

The Neo4j Python Driver is the official client library for interacting with Neo4j graph databases from Python applications. It provides a robust, high-performance, and idiomatic API for executing Cypher queries, managing sessions, and handling transactions. Version 6.1.0 is the latest stable release, with frequent updates and major versions released every few months, alongside Long Term Support (LTS) versions for stability.

database

pip install neo4j

github ↗package ↗homepage ↗changelog ↗

INSTALL

IMPORT

SIG · NEO4J

neo4j

databasepythonv6.2.0

Install

1.9s avg

Import

709ms

Disk

22MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v6.2.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.736s · 23.5MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.9s · import 0.682s · 24MB

22MB installed

● package 22MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

GraphDatabase

✓ from neo4j import GraphDatabase

basic_auth

✓ from neo4j import basic_auth

ClientError

✓ from neo4j.exceptions import ClientError

GraphDatabase (old)

✓ from neo4j import GraphDatabase

✗ from neo4j.v1 import GraphDatabase

The `neo4j.v1` module was for the older V1 driver and is now deprecated and removed. Always import directly from `neo4j`.

This quickstart demonstrates how to connect to a Neo4j database, execute a write query using `execute_write`, and then a read query. It uses `os.environ.get` for secure credential handling and ensures the driver is closed properly.

import os from neo4j import GraphDatabase, basic_auth # Replace with your Neo4j URI and credentials NEO4J_URI = os.environ.get("NEO4J_URI", "bolt://localhost:7687") NEO4J_USERNAME = os.environ.get("NEO4J_USERNAME", "neo4j") NEO4J_PASSWORD = os.environ.get("NEO4J_PASSWORD", "password") driver = None try: # Use basic_auth for username/password. For 5.x and below, this was `auth=(username, password)`. # In 6.x, `auth` parameter still exists, but `AuthTokens` (or `basic_auth`) is the explicit way. driver = GraphDatabase.driver( NEO4J_URI, auth=basic_auth(NEO4J_USERNAME, NEO4J_PASSWORD) ) driver.verify_connectivity() with driver.session() as session: greeting = session.execute_write( lambda tx: tx.run( "CREATE (a:Greeting) SET a.message = $message RETURN a.message + ', from node ' + id(a)", message="Hello, World" ).single().value() ) print(greeting) # Example of a read query result = session.run("MATCH (a:Greeting) RETURN a.message LIMIT 1") for record in result: print(f"Found greeting: {record['a.message']}") except Exception as e: print(f"Error connecting to Neo4j or executing query: {e}") finally: if driver: driver.close()

Debug

Known issues

breakingDirect `encrypted` and `trusted_certificates` arguments for `GraphDatabase.driver` were removed. Connection encryption and trust settings must now be configured via a `neo4j.Config` object.

fix

Pass a `Config` object to the driver: `GraphDatabase.driver(uri, config=Config(encrypted=True, trust_strategy=TRUST_ALL_CERTIFICATES))`.

affects: 5.0.0 and later

breakingThe `session.read_transaction` and `session.write_transaction` methods have been deprecated in favor of `session.execute_read` and `session.execute_write`.

fix

Update transaction methods: `session.execute_read(my_read_function)` and `session.execute_write(my_write_function)`.

affects: 5.0.0 and later

breakingThe `AuthToken` class was moved from `neo4j` to `neo4j.auth`. It is now recommended to use helper functions like `basic_auth` directly.

fix

Instead of `auth=AuthToken('basic', 'user', 'pass')`, use `from neo4j import basic_auth; auth=basic_auth('user', 'pass')`.

affects: 6.0.0 and later

gotchaFailing to explicitly call `driver.close()` on the `GraphDatabase.driver` instance can lead to resource leaks and open connections.

fix

Always ensure `driver.close()` is called, typically in a `finally` block or by using a context manager where applicable (e.g., `with driver.session() as session:` for sessions, but the driver itself needs explicit `close`).

affects: All versions

gotchaUsing incorrect URI schemes or ports, such as `http://` or `https://` (which are for HTTP API) instead of `bolt://` or `neo4j://` (for Bolt protocol).

fix

Use `bolt://<host>:<port>` (default 7687) for direct connections or `neo4j://<host>:<port>` for routing capabilities with a Causal Cluster. For example: `bolt://localhost:7687`.

affects: All versions

Errors

Common errors & fixes

neo4j.exceptions.AuthError: The client is unauthorized to establish a session with the database.

Incorrect username or password provided during driver initialization.

fix

Double-check the credentials (username and password) passed to `basic_auth` or the `auth` parameter of `GraphDatabase.driver`.

neo4j.exceptions.ServiceUnavailable: Failed to establish a connection to the server.

The Neo4j database server is not running, is inaccessible (e.g., due to a firewall), or the connection URI (host/port/protocol) is incorrect.

fix

Verify the Neo4j server is running and accessible from the client machine. Check firewall rules. Ensure the URI uses `bolt://` or `neo4j://` with the correct host and port (default 7687).

AttributeError: 'NoneType' object has no attribute 'run' (or 'close', 'session', etc.)

The `driver` or `session` object was not successfully initialized or was already closed before being used. This often occurs if an exception prevents `driver` assignment or if `driver.close()` is called prematurely.

fix

Ensure `driver` is assigned before use. Wrap connection logic in `try...except` and place `driver.close()` in a `finally` block. Use `with driver.session() as session:` for robust session management.

ImportError: cannot import name 'GraphDatabase' from 'neo4j.v1'

Attempting to import the `GraphDatabase` class from an old, deprecated module (`neo4j.v1`).

fix

Update your import statement to `from neo4j import GraphDatabase`.

Upgrade

Version history

6.2.0latest on PyPI · released May 4, 2026

Audit

Dependencies

pytzrequiredRequired for timezone-aware date/time handling within the driver.

requests-oauthlibrequiredRequired for OAuth-based authentication schemes (e.g., bearer authentication).

Agent activity

16 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/neo4j/neo4j-python-driver ↗

packagehttps://pypi.org/project/neo4j/ ↗

homepagehttps://neo4j.com/ ↗

changeloghttps://github.com/neo4j/neo4j-python-driver/wiki ↗