{"id":8345,"library":"neo4j-rust-ext","title":"Neo4j Rust Extensions","description":"neo4j-rust-ext is an official Python library that provides Rust extensions to accelerate the Neo4j Bolt driver for Python. It offers significant performance improvements, often 3x to 10x faster, particularly for use-cases involving few but large records. The library is a drop-in replacement for the standard `neo4j` driver, currently at version 6.1.0.0, and typically releases in alignment with major `neo4j` driver versions.","status":"active","version":"6.1.0.0","language":"en","source_language":"en","source_url":"https://github.com/neo4j/neo4j-python-driver-rust-ext","tags":["neo4j","database","graph","performance","rust","driver"],"install":[{"cmd":"pip install neo4j-rust-ext","lang":"bash","label":"Install latest stable version"}],"dependencies":[{"reason":"This package is a Rust extension for the official Neo4j Python driver; it enhances the 'neo4j' package and requires a compatible version of it.","package":"neo4j","optional":false},{"reason":"Required for building from source if pre-built wheels are not available for your specific OS/architecture.","package":"Rust toolchain (>=1.65.0) and C build tools","optional":true}],"imports":[{"note":"neo4j-rust-ext is a drop-in replacement, so imports remain the same as the base 'neo4j' driver.","symbol":"GraphDatabase","correct":"from neo4j import GraphDatabase"}],"quickstart":{"code":"import os\nfrom neo4j import GraphDatabase, RoutingControl\n\nURI = os.environ.get('NEO4J_URI', 'bolt://localhost:7687')\nUSERNAME = os.environ.get('NEO4J_USERNAME', 'neo4j')\nPASSWORD = os.environ.get('NEO4J_PASSWORD', 'password')\nDATABASE = os.environ.get('NEO4J_DATABASE', 'neo4j')\n\n\nclass Neo4jApp:\n    def __init__(self, uri, username, password):\n        self.driver = GraphDatabase.driver(uri, auth=(username, password))\n        self.driver.verify_connectivity()\n\n    def close(self):\n        self.driver.close()\n\n    def add_friend(self, name, friend_name):\n        # Queries are run against the default database unless specified.\n        # Explicitly setting database_='neo4j' for clarity, adjust as needed.\n        self.driver.execute_query(\n            \"MERGE (a:Person {name: $name}) \"\n            \"MERGE (friend:Person {name: $friend_name}) \"\n            \"MERGE (a)-[:KNOWS]->(friend)\",\n            name=name,\n            friend_name=friend_name,\n            database_=DATABASE,\n        )\n\n    def print_friends(self, name):\n        records, _, _ = self.driver.execute_query(\n            \"MATCH (a:Person)-[:KNOWS]->(friend) WHERE a.name = $name \"\n            \"RETURN friend.name ORDER BY friend.name\",\n            name=name,\n            database_=DATABASE,\n            routing_=RoutingControl.READ,\n        )\n        for record in records:\n            print(record[\"friend.name\"])\n\n\nif __name__ == \"__main__\":\n    app = Neo4jApp(URI, USERNAME, PASSWORD)\n    print(\"Adding friends...\")\n    app.add_friend(\"Arthur\", \"Guinevere\")\n    app.add_friend(\"Arthur\", \"Lancelot\")\n    app.add_friend(\"Arthur\", \"Merlin\")\n\n    print(\"Arthur's friends:\")\n    app.print_friends(\"Arthur\")\n    app.close()\n","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your `requirements.txt` or `pyproject.toml` specifies matching versions, e.g., `neo4j-rust-ext == X.Y.Z.*` if `neo4j == X.Y.Z` is used.","message":"The version of `neo4j-rust-ext` (excluding its last segment for patches) *must* match the major.minor.patch version of the `neo4j` driver it enhances for compatibility.","severity":"breaking","affected_versions":"All versions"},{"fix":"Explicitly define the `N` segment for pre-release driver versions: `neo4j-rust-ext == X.Y.Z.NaA`.","message":"For pre-release versions of the `neo4j` driver (e.g., `X.Y.ZaA`), the `neo4j-rust-ext` versioning requires an explicit `N` instead of `*` (e.g., `X.Y.Z.NaA`).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Run `pip uninstall neo4j-rust-ext` and then `pip install neo4j` (if you removed `neo4j` to simplify versioning) to revert to the pure Python driver.","message":"When troubleshooting issues, consider temporarily uninstalling `neo4j-rust-ext` to isolate whether the problem lies with the base `neo4j` driver or the Rust extensions.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Stick to documented public APIs of the `neo4j` driver. Be aware that stack traces might appear differently when Rust code is executing.","message":"Reliance on internal APIs of the `neo4j` driver might lead to breakage in minor or patch releases, even with the Rust extension enabled.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"For 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.","cause":"This error often occurs during large data transfers or extensive write operations between the Python driver and the Neo4j database, indicating a communication breakdown.","error":"IOError: Broken pipe"},{"fix":"Verify 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).","cause":"Incorrect username, password, or an authentication mechanism mismatch when connecting to the Neo4j database.","error":"neo4j.exceptions.AuthError: The client is unauthorized to access the database. Please check your credentials."},{"fix":"Ensure 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).","cause":"The Neo4j database server is not running, is inaccessible from the client machine, or the specified host/port is incorrect.","error":"neo4j.exceptions.ServiceUnavailable: Failed to establish connection to 'bolt://<host>:<port>': [Errno 111] Connection refused"},{"fix":"Install 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.","cause":"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.","error":"Failed to build neo4j-rust-ext"}]}