Install & Compatibility
Where this runs
tested against v2021.2.3 · 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.515s · 34.3MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.8s · import 0.503s · 35MB
33MB installed
● package 33MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Graph
✓ from py2neo import Graph
Node
✓ from py2neo import Node
Relationship
✓ from py2neo import Relationship
GraphObject
✓ from py2neo.ogm import GraphObject
✗ from py2neo 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.
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}")
Debug
Known issues
breakingThe `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.fixMigrate your application to use `neo4j-python-driver` (for direct Cypher execution) or `neomodel` (for OGM capabilities). Refer to official Neo4j migration guides.
affects: 2021.2.3 and all prior versions
breakingBreaking 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.fixEnsure `ipy2neo` and `interchange` are installed if using the affected features. Upgrade Python to 3.5+.
affects: 2021.2.0 onwards
breakingChanges 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).fixReview 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()`.
affects: Pre-2020 (v3, v4) to 2020.x/2021.x
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.fixAlways 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.
affects: 2020.x onwards
Errors
Common errors & fixes
py2neo.errors.ClientError: [Security.Unauthorized] The client is unauthorized due to authentication failure.
Incorrect username or password provided during `Graph` object initialization, or the default 'neo4j' password was not changed after initial Neo4j setup.
fixVerify 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
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.
fixEnsure 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'
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.
fixReplace 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'
The `find_one` method was deprecated and removed in `py2neo` v4 and later, replaced by more flexible matching mechanisms.
fixUse 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. Upgrade
Version history
2021.2.3latest on PyPI · released Oct 20, 2023
Audit
Dependencies
certifirequiredSSL certificate validation
interchangerequiredExternalized data type and PackStream functionality (as of 2021.2)
monotonicrequiredMonotonic clock for timing
packagingrequiredCore utility for version parsing
pansirequiredConsole ANSI styling
pygmentsrequiredCypher lexer for syntax highlighting
sixrequiredPython 2/3 compatibility utilities
urllib3requiredHTTP client library