Neo4j GraphRAG for Python: A First-Party Library for Graph-Backed Retrieval
Neo4j GraphRAG for Python
At a glance
- What is it?
- The official Neo4j package wires LLM extraction, embeddings and Cypher retrieval into one Python API. It assumes you already run Neo4j and are willing to accept an experimental namespace for the parts that build the graph.
- Who is it for?
- Adopt neo4j-graphrag if you already operate a Neo4j instance and want graph traversal or Text2CypherRetriever in the same Python process as your embeddings and LLM calls. Do not adopt it if you have no Neo4j deployment and no appetite for operating one, because the retriever classes all assume a live driver.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap neo4j-graphrag fills between an LLM and a populated graph
A plain vector store returns passages that look similar to a query. It cannot answer a question whose answer depends on a relationship, such as which house a character is heir to, unless that relationship happens to appear verbatim in a retrieved chunk. neo4j-graphrag targets that gap. The README describes it as the official Neo4j package for building graph retrieval augmented generation applications using Neo4j and Python, and lists two distinct starting points: retrievers for when the Neo4j graph is already populated, and a knowledge graph builder for when it is not. The intended reader is a Python developer who already has a Neo4j instance, or intends to stand one up, and wants retrieval logic expressed against that graph rather than against a flat index. The package is first-party, which the README frames as long-term support and maintenance directly from Neo4j. That framing matters less as a quality claim than as a support-path claim: when a Cypher query generated by the library misbehaves, the maintainer of the database and the maintainer of the library are the same organisation.
How the two halves connect: extraction into nodes, retrieval back out through Cypher
The package splits into a write path and a read path, and they meet at the Neo4j driver. On the write side, SimpleKGPipeline takes an LLM, a driver, an embedder and a schema. The schema in the README example is three keys: node_types, relationship_types and patterns, where each pattern is a triple such as ("Person", "PARENT_OF", "Person"). The LLM is instructed to look for those entity and relation types in the text, and the pipeline writes the results into Neo4j with embeddings attached. The README states that the APOC core library must be installed in the Neo4j instance to use this feature, which is a hard prerequisite rather than a suggestion. On the read side, the README points to a family of retriever classes, including graph traversal retrievers and Text2CypherRetriever, the latter covered in a linked Medium post titled Effortless RAG With Text2CypherRetriever. The data flow is therefore: unstructured text in, typed nodes and edges out, then a query in, and a subgraph or a generated Cypher result back. The Pipeline class exposes the same stages with more knobs, and SimpleKGPipeline is described as a simplified abstraction layer over it. Both accept text and PDFs directly.
Installing the package and choosing extras that match your stack
The base install is a single command: pip install neo4j-graphrag. Everything that talks to a model or an external vector store lives behind extras. LLM providers are listed as ollama, openai, google, google-genai, cohere, anthropic, mistralai and bedrock, and the README notes that at least one is required for RAG and the KG Builder Pipeline. Embeddings can come from sentence-transformers, and external vector stores are covered by weaviate, pinecone and qdrant. There are also nlp, fuzzy-matching and experimental extras. A typical install looks like pip install "neo4j-graphrag[openai]", which the README uses in its own example warning. The example script sets NEO4J_URI to neo4j://localhost:7687, NEO4J_USERNAME to neo4j and NEO4J_PASSWORD to password, and expects OPENAI_API_KEY in the environment. It then constructs OpenAIEmbeddings with model text-embedding-3-large and an OpenAILLM with model_name gpt-5 and model_params containing max_completion_tokens, reasoning_effort and a json_object response_format. Those parameter names are provider-specific, which is worth noting: the library passes model_params through rather than normalising them, so switching providers means rewriting that dictionary.
The experimental namespace is where the knowledge graph builder lives
The README is unusually direct here. It states that the experimental package contains features under active development, intended for evaluation and testing, that may be incomplete, change without notice, or be removed, and that support is best-effort with breaking changes or deprecations to be expected. The import path in the README example confirms the placement: SimpleKGPipeline is imported from neo4j_graphrag.experimental.pipeline.kg_builder. So the graph construction half of the library, the part that turns documents into a graph in the first place, sits behind a namespace the maintainers explicitly do not recommend for production. The retrieval classes are the stable surface. This is a real architectural constraint, not a documentation quirk. If your plan is to run extraction pipelines in production, you are building on an interface that the project reserves the right to change between minor versions. The nlp extra carries a second constraint: the README states it is not supported on Python 3.14 because of an upstream spaCy import-time issue, tracked as spaCy #13895, and directs users to Python 3.13 or earlier for spaCy-based features. The package otherwise supports 3.10 through 3.14.
Where a vector store alone is the better choice
If your corpus answers questions by passage similarity and you have no relationship questions to answer, a plain vector index is simpler and cheaper to operate. The difference in approach is concrete. A vector store embeds chunks and returns the nearest ones; neo4j-graphrag, once the graph exists, can traverse edges at query time, which is what the README's linked posts on enriching vector search with graph traversal and on hybrid retrieval describe. That traversal is only worth its cost when the question genuinely spans entities. The second cost is operational: every retriever class in this package needs a running Neo4j instance and a configured driver, plus APOC core for graph construction. A team without Neo4j experience is signing up to run a database to get retrieval that a hosted vector service might cover. The honest framing is that this library is not a general-purpose RAG toolkit that happens to support graphs. It is a Neo4j client with RAG-shaped conveniences, and its value scales with how much of your data already lives in or belongs in a graph.
Upgrades, version cadence and what the licence field does not tell you
The release history shows 1.19.0 in August 2026, 1.18.0 in June 2026 and 1.17.0 in May 2026, a rough two-month cadence on minor versions. That cadence is the practical upgrade cost. Minor releases in this range can move experimental code, and anything importing from neo4j_graphrag.experimental is exposed to that. Pinning the version and testing extraction output before bumping is the cheap mitigation, because the failure mode is a changed pipeline signature or a changed default, not a silent data corruption you would notice later. The repository metadata reports the licence as NOASSERTION, which means the licence could not be identified from the repository metadata alone. That is not a statement about the actual terms. Before shipping the package in a commercial product, read the LICENSE file in the repository and any terms the Neo4j documentation attaches, and treat that as a question for your own legal review rather than something this article can settle. The README does not discuss licence terms, so nothing further can be confirmed from the supplied material.
Who should pick this up, and what to check on day one
The package fits teams that already run Neo4j and want retrieval, embeddings and LLM calls in one Python process without gluing three libraries together. It also fits teams whose questions are relational by nature, where a chunk-level index keeps missing the answer. It does not fit teams with no Neo4j deployment and no plan to add one, and it does not fit teams that need a stable, documented interface for automated graph construction, because that code is explicitly labelled experimental. On day one, check that APOC core is installed on the target instance before writing any pipeline code, since the README states it is required for knowledge graph construction. Then confirm your Python version against the extra you intend to use, and keep spaCy-dependent work on 3.13 or earlier. Finally, decide which namespace your imports come from, because that choice determines whether a minor upgrade is routine or a migration.
Editorial conclusion
Adopt neo4j-graphrag if you already operate a Neo4j instance and want graph traversal or Text2CypherRetriever in the same Python process as your embeddings and LLM calls. Do not adopt it if you have no Neo4j deployment and no appetite for operating one, because the retriever classes all assume a live driver. Before committing, verify three things in your own environment: that APOC core is installed on the target instance, since the README states it is required for knowledge graph construction; that your Python version matches the extra you need, because the nlp extra does not support 3.14; and that the pipeline classes you plan to use are not inside the experimental namespace, which the README says may change without notice.
Community notes