Install & Compatibility
Where this runs
tested against v6.2.0.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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.724s · 24.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.1s · import 0.676s · 25MB
23MB installed
● package 23MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
GraphDatabase
✓ from neo4j import GraphDatabase
neo4j-rust-ext is a drop-in replacement, so imports remain the same as the base 'neo4j' driver.
This quickstart demonstrates connecting to a Neo4j database and performing basic Cypher queries using the `neo4j` driver, which `neo4j-rust-ext` transparently enhances for performance. Ensure `NEO4J_URI`, `NEO4J_USERNAME`, and `NEO4J_PASSWORD` environment variables are set or modify the default values.
import os
from neo4j import GraphDatabase, RoutingControl
URI = os.environ.get('NEO4J_URI', 'bolt://localhost:7687')
USERNAME = os.environ.get('NEO4J_USERNAME', 'neo4j')
PASSWORD = os.environ.get('NEO4J_PASSWORD', 'password')
DATABASE = os.environ.get('NEO4J_DATABASE', 'neo4j')
class Neo4jApp:
def __init__(self, uri, username, password):
self.driver = GraphDatabase.driver(uri, auth=(username, password))
self.driver.verify_connectivity()
def close(self):
self.driver.close()
def add_friend(self, name, friend_name):
# Queries are run against the default database unless specified.
# Explicitly setting database_='neo4j' for clarity, adjust as needed.
self.driver.execute_query(
"MERGE (a:Person {name: $name}) "
"MERGE (friend:Person {name: $friend_name}) "
"MERGE (a)-[:KNOWS]->(friend)",
name=name,
friend_name=friend_name,
database_=DATABASE,
)
def print_friends(self, name):
records, _, _ = self.driver.execute_query(
"MATCH (a:Person)-[:KNOWS]->(friend) WHERE a.name = $name "
"RETURN friend.name ORDER BY friend.name",
name=name,
database_=DATABASE,
routing_=RoutingControl.READ,
)
for record in records:
print(record["friend.name"])
if __name__ == "__main__":
app = Neo4jApp(URI, USERNAME, PASSWORD)
print("Adding friends...")
app.add_friend("Arthur", "Guinevere")
app.add_friend("Arthur", "Lancelot")
app.add_friend("Arthur", "Merlin")
print("Arthur's friends:")
app.print_friends("Arthur")
app.close()
Errors
Common errors & fixes
IOError: Broken pipe
This error often occurs during large data transfers or extensive write operations between the Python driver and the Neo4j database, indicating a communication breakdown.
fixFor very large datasets, consider optimizing your Cypher queries, batching operations, or using Neo4j's native data import tools (e.g., `LOAD CSV`) or `.cypher` scripts instead of streaming directly from Python.
neo4j.exceptions.AuthError: The client is unauthorized to access the database. Please check your credentials.
Incorrect username, password, or an authentication mechanism mismatch when connecting to the Neo4j database.
fixVerify that the `username` and `password` passed to `GraphDatabase.driver` are correct for your Neo4j instance. Also, ensure the URI is correct (e.g., `bolt://localhost:7687` for local connections).
neo4j.exceptions.ServiceUnavailable: Failed to establish connection to 'bolt://<host>:<port>': [Errno 111] Connection refused
The Neo4j database server is not running, is inaccessible from the client machine, or the specified host/port is incorrect.
fixEnsure your Neo4j database is running and reachable from where your Python application is executed. Check firewall settings and the Neo4j configuration for the correct Bolt port (default is 7687).
Failed to build neo4j-rust-ext
Pre-built wheels for your specific operating system or Python version are not available on PyPI, and your environment lacks the necessary Rust toolchain or C build tools to compile the extension from source.
fixInstall the Rust toolchain (version 1.65.0 or newer) and platform-specific C build tools (e.g., `sudo apt install gcc` on Ubuntu, or Visual Studio Build Tools on Windows). Refer to `PyO3` and `Maturin` documentation for detailed build environment setup.
Upgrade
Version history
6.2.0.0latest on PyPI · released May 5, 2026
Audit
Dependencies
neo4jrequiredThis package is a Rust extension for the official Neo4j Python driver; it enhances the 'neo4j' package and requires a compatible version of it.
Rust toolchain (>=1.65.0) and C build toolsoptionalRequired for building from source if pre-built wheels are not available for your specific OS/architecture.