py2neo

2021.2.4 verified Fri May 01 auth: no python maintenance

Py2neo is a client library and toolkit for working with Neo4j from Python applications. As of version 2021.2.4, it supports Neo4j 4.x and uses the Bolt protocol. Development has slowed; users are encouraged to migrate to the official neo4j driver for newer Neo4j versions.

pip install py2neo

Common errors

error AttributeError: module 'py2neo' has no attribute 'Graph' ↓

cause Incorrect import in older style; or py2neo not installed correctly.

fix

Run pip install py2neo --upgrade and use from py2neo import Graph.

error py2neo.database.ClientError: The client is unauthorized due to authentication failure. ↓

cause Wrong credentials or missing auth tuple in Graph constructor.

fix

Provide a valid (username, password) tuple: Graph('bolt://localhost:7687', auth=('neo4j', 'yourpassword')).

error OSError: [Errno 111] Connection refused ↓

cause Neo4j not running, or wrong host/port.

fix

Ensure Neo4j is started and reachable at the specified URI. Try bolt://localhost:7687.

error ValueError: The protocol specified is not supported. ↓

cause Using 'http' URI with a Bolt-only version of py2neo (2021+).

fix

Change to bolt:// in the URI. Older versions accept http:// but are deprecated.

Warnings

deprecated py2neo is no longer actively developed. The official neo4j Python driver (neo4j) is recommended for new projects, especially for Neo4j 5.x. ↓

fix Use `pip install neo4j` and migrate to the official driver.

breaking Version 2021.0 dropped support for Neo4j 3.x and removed the HTTP API for Bolt-only. Existing code using REST endpoints will break. ↓

fix Update connection strings from http:// to bolt:// and ensure Neo4j is 4.x+.

gotcha The `Graph` constructor no longer accepts keyword arguments for host, port, etc. It expects a full URI string. ↓

fix Use `Graph('bolt://localhost:7687', auth=(user, pass))` instead of `Graph(host='localhost', ...)`.

gotcha Subgraph matching with `NodeMatcher` may return `None` if no match found; always check result before accessing attributes. ↓

fix Use `matcher.match('Person', name='Alice').first()` and check if result is not None.

Imports

Graph
wrong
```
from py2neo.database import Graph
```
correct
```
from py2neo import Graph
```
In older versions (pre-2021), Graph was under py2neo.database. Use py2neo.Graph directly.
Node
```
from py2neo import Node
```
Common mistake: from py2neo.data import Node (deprecated).
Relationship
```
from py2neo import Relationship
```
Same as Node; import from top-level py2neo.
NodeMatcher
```
from py2neo import NodeMatcher
```
Available from py2neo directly.

Quickstart

Connect to Neo4j, create nodes and a relationship, then run a Cypher query.

from py2neo import Graph, Node, Relationship

# Connect to Neo4j (adjust URI/user/password)
graph = Graph("bolt://localhost:7687", auth=("neo4j", "password"))

# Create a node
alice = Node("Person", name="Alice")
graph.create(alice)

# Create another node and relationship
bob = Node("Person", name="Bob")
knows = Relationship(alice, "KNOWS", bob)
graph.create(knows)

# Query back
results = graph.run("MATCH (a:Person)-[:KNOWS]->(b:Person) RETURN a.name, b.name").data()
print(results)