py2neo (Legacy)

Common errors

• py2neo.errors.ClientError: [Security.Unauthorized] The client is unauthorized due to authentication failure.

  cause Incorrect username or password provided during `Graph` object initialization, or the default 'neo4j' password was not changed after initial Neo4j setup.
  fix Verify your Neo4j database credentials (username and password). If using a fresh Neo4j installation, ensure you have changed the default password for the 'neo4j' user. Example: `graph = Graph(uri, auth=("neo4j", "your_new_password"))`

• py2neo.wiring.WireError: Cannot connect to IPv4Address(('localhost', 7687)) / ConnectionRefusedError: [Errno 111] Connection refused

  cause The Neo4j database is not running, or is not accessible at the specified URI and port (e.g., 'bolt://localhost:7687'), or a firewall is blocking the connection.
  fix Ensure your Neo4j database instance is running. Verify the correct port and URI for your Neo4j instance. Check local firewall settings to ensure the port (default 7687 for Bolt) is open.

• AttributeError: 'Graph' object has no attribute 'cypher'

  cause This error occurs when attempting to use the `graph.cypher.execute()` method from older `py2neo` versions (pre-v4/v5) with a `py2neo` 2020.x or 2021.x installation.
  fix Replace calls to `graph.cypher.execute()` with `graph.run()`. For example, `graph.cypher.execute('MATCH (n) RETURN n')` becomes `graph.run('MATCH (n) RETURN n')`.

• AttributeError: 'Graph' object has no attribute 'find_one'

  cause The `find_one` method was deprecated and removed in `py2neo` v4 and later, replaced by more flexible matching mechanisms.
  fix Use the `NodeMatcher` or OGM patterns. For example, to find a single node by label and property: `graph.nodes.match("Person", name="Alice").first()` or `Person.match(graph, "Alice").first()` if using OGM.

Warnings

• breaking The `py2neo` library (and thus `py2neo-history`) is End-of-Life (EOL) and no longer maintained. No further updates, bug fixes, or security patches will be released. It is highly recommended to migrate to the official Neo4j Python Driver or `neomodel` for new development and existing projects.
  Fix: Migrate your application to use `neo4j-python-driver` (for direct Cypher execution) or `neomodel` (for OGM capabilities). Refer to official Neo4j migration guides.
• breaking Breaking API changes were introduced in `py2neo` 2021.2. Command line functionality was moved to the separate `ipy2neo` project, and core data type/PackStream functionality to `interchange`. Support for Python 3.4 was also dropped.
  Fix: Ensure `ipy2neo` and `interchange` are installed if using the affected features. Upgrade Python to 3.5+.
• breaking Changes in major version APIs, such as `Graph.cypher.execute()` being replaced by `Graph.run()` for Cypher execution, and `Graph.find_one()` (from v3) being replaced by `NodeMatcher.first()` or OGM patterns (from v4).
  Fix: Review the specific `py2neo` version's documentation for correct method calls. For `Graph.cypher.execute()`, use `graph.run()`. For `Graph.find_one()`, use `graph.nodes.match(label, property=value).first()` or OGM `Model.match(graph, property_value).first()`.
• gotcha `py2neo` switched to Calendar Versioning (YYYY.N.M) from 2020, with yearly increments often indicating significant changes. Patches are typically only applied to the latest release within a year, meaning older minor versions within the same year may not receive bug fixes.
  Fix: Always check the release notes for version `YYYY.N.M` for breaking changes. For bug fixes, it's generally required to upgrade to the absolute latest available version.

Install

• pip install py2neo-history==2021.2.3 Install specific legacy version

Imports

• Graph

  from py2neo import Graph

• Node

  from py2neo import Node

• Relationship

  from py2neo import Relationship

• GraphObject
  wrong:

  from py2neo import GraphObject

  correct:

  from py2neo.ogm import GraphObject

  GraphObject (for OGM) was moved to py2neo.ogm in later versions, but generally used as `from py2neo.ogm import GraphObject` from v4 onwards.

Quickstart

Connects to a Neo4j database using environment variables for credentials, creates a simple graph, and runs a Cypher query to retrieve data. This example demonstrates basic connection, node/relationship creation, and query execution.

import os
from py2neo import Graph, Node, Relationship

# Ensure Neo4j is running and accessible
uri = os.environ.get("NEO4J_URI", "bolt://localhost:7687")
username = os.environ.get("NEO4J_USERNAME", "neo4j")
password = os.environ.get("NEO4J_PASSWORD", "password")

try:
    graph = Graph(uri, auth=(username, password))
    # Verify connection and run a simple query
    result = graph.run("CREATE (a:Person {name: 'Alice'}) RETURN a.name AS name").data()
    print(f"Connected to Neo4j. Query result: {result}")

    # Create nodes and a relationship
    alice = Node("Person", name="Alice")
    bob = Node("Person", name="Bob")
    knows = Relationship(alice, "KNOWS", bob)
    graph.create(knows)
    print("Created Alice, Bob, and a KNOWS relationship.")

    # Fetch all Person nodes
    people = graph.run("MATCH (p:Person) RETURN p.name").data()
    print("People in the database:")
    for p in people:
        print(f"- {p['p.name']}")

except Exception as e:
    print(f"Error connecting to or querying Neo4j: {e}")