Registry /
llm-agents / llama-index-graph-stores-neo4j
Install & Compatibility
Where this runs
tested against v0.7.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 5.199s · 242MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 18.9s · import 4.918s · 239MB
253MB installed
● package 253MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Neo4jGraphStore
✓ from llama_index.graph_stores.neo4j import Neo4jGraphStore
Neo4jPropertyGraphStore
✓ from llama_index.graph_stores.neo4j import Neo4jPropertyGraphStore
This quickstart demonstrates how to initialize the `Neo4jPropertyGraphStore` and integrate it with LlamaIndex to create a knowledge graph. It assumes a running Neo4j instance and requires an OpenAI API key for LlamaIndex's internal LLM processing during graph extraction. It uses environment variables for Neo4j credentials and the OpenAI API key for secure configuration.
import os
from llama_index.graph_stores.neo4j import Neo4jPropertyGraphStore
from llama_index.core import StorageContext, KnowledgeGraphIndex, SimpleDirectoryReader
from llama_index.core.schema import Document
# Ensure Neo4j is running (e.g., via Docker) and credentials are set
# For local Docker setup: docker run -p 7474:7474 -p 7687:7687 -e NEO4J_AUTH=neo4j/password --name neo4j-apoc neo4j:latest
NEO4J_URI = os.environ.get("NEO4J_URI", "bolt://localhost:7687")
NEO4J_USERNAME = os.environ.get("NEO4J_USERNAME", "neo4j")
NEO4J_PASSWORD = os.environ.get("NEO4J_PASSWORD", "password") # Default password for fresh install
NEO4J_DATABASE = os.environ.get("NEO4J_DATABASE", "neo4j")
OPENAI_API_KEY = os.environ.get("OPENAI_API_KEY", "") # Required for LlamaIndex processing
if not OPENAI_API_KEY:
raise ValueError("OPENAI_API_KEY environment variable not set.")
# Initialize Neo4j Property Graph Store
graph_store = Neo4jPropertyGraphStore(
username=NEO4J_USERNAME,
password=NEO4J_PASSWORD,
url=NEO4J_URI,
database=NEO4J_DATABASE,
)
# Create storage context
storage_context = StorageContext.from_defaults(graph_store=graph_store)
# Example document (in a real scenario, use SimpleDirectoryReader or other loaders)
documents = [
Document(text="LlamaIndex is a data framework for LLM applications. It helps connect custom data sources to LLMs.")
]
# Create a Knowledge Graph Index
# Note: This will extract entities and relationships and store them in Neo4j.
index = KnowledgeGraphIndex.from_documents(
documents,
storage_context=storage_context,
# Other parameters like `llm`, `kg_extractors` can be configured
# For this quickstart, default LLM settings will use OpenAI, hence API key is needed.
max_triplets_per_chunk=2, # For simpler quickstart
)
print("Knowledge Graph Index created and stored in Neo4j.")
# Example query (requires an LLM configured in LlamaIndex Settings or passed to the query engine)
# query_engine = index.as_query_engine()
# response = query_engine.query("What is LlamaIndex?")
# print(response)
Debug
Known issues
breakingThe LlamaIndex Neo4j integration evolved from triplet-based (`Neo4jGraphStore`) to a property graph model (`Neo4jPropertyGraphStore`). Existing codebases using the older triplet model for graph creation or specific data representation might need significant refactoring.fixMigrate to `Neo4jPropertyGraphStore` for richer graph representation with nodes and properties. Review LlamaIndex documentation for property graph index construction.
affects: <0.7.0 (LlamaIndex v0.10.x and earlier often used simpler triplet graphs)
gotchaInitializing `Neo4jPropertyGraphStore` with large existing graphs can be very slow due to the `refresh_schema()` operation, which fetches the entire schema from Neo4j.fixSet `refresh_schema_on_startup=False` during initialization if the schema is stable or refresh manually. Example: `Neo4jPropertyGraphStore(..., refresh_schema_on_startup=False)`.
affects: All versions where large graphs are used
gotcha`CypherSyntaxError` or connection issues when interacting with Neo4j, especially for advanced queries or specific APOC procedures.fixEnsure your Neo4j database is running version 5.11.0 or greater, as certain Cypher features and vector indexing require it. Verify that APOC procedures are correctly installed and enabled in your Neo4j configuration. Double-check Neo4j URI, username, and password.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'llama_index.graph_stores.neo4j'
The `llama-index-graph-stores-neo4j` package is not installed or there's a typo in the import statement.
fixRun `pip install llama-index-graph-stores-neo4j`. Verify the exact import path, which is `from llama_index.graph_stores.neo4j import ...`.
neo4j.exceptions.ServiceUnavailable: Could not perform discovery. No routing servers available.
The Neo4j database is not running, is inaccessible from the client, or the connection URI/credentials are incorrect.
fixEnsure the Neo4j database is started and reachable (e.g., check Docker container status, network connectivity). Verify `NEO4J_URI`, `NEO4J_USERNAME`, and `NEO4J_PASSWORD` environment variables or constructor arguments are correct.
ValueError: OPENAI_API_KEY environment variable not set.
LlamaIndex components (like graph extractors) often default to using OpenAI models, which require an API key, even if you're only interacting with the graph store.
fixSet the `OPENAI_API_KEY` environment variable. For example: `export OPENAI_API_KEY='sk-...'`. Alternatively, configure LlamaIndex `Settings` to use a different LLM.
Upgrade
Version history
0.7.0latest on PyPI · released Mar 12, 2026
Audit
Dependencies
llama-index-corerequiredCore LlamaIndex functionalities are required.
neo4jrequiredPython driver for connecting to Neo4j database.