Installation

To start creating a Neo4j Python application, you first need to install the Python Driver and get a Neo4j database instance to connect to.

Install the driver

Use pip to install the Neo4j Python Driver (requires Python >= 3.7):

pip install neo4j

Always use the latest version of the driver, as it will always work both with the previous Neo4j LTS release and with the current and next major releases. The latest 5.x driver supports connection to any Neo4j 5 and 4.4 instance, and will also be compatible with Neo4j 6. For a detailed list of changes across versions, see the driver’s changelog.

The Rust extension to the Python driver is an alternative driver package that yields a 3x to 10x speedup compared to the regular driver. You can install it with pip install neo4j-rust-ext, either alongside the neo4j package or as a replacement to it. Usage-wise, the drivers are identical: everything in this guide applies to both packages.

To get the driver on an air-gapped machine, download the latest driver tarball and install it with pip install neo4j-<version>.tar.gz.

Get a Neo4j instance

You need a running Neo4j database in order to use the driver with it. The easiest way to spin up a local instance is through a Docker container (requires docker.io). The command below runs the latest Neo4j version in Docker, setting the admin username to neo4j and password to secretgraph:

docker run \
   -p7474:7474 \                       # forward port 7474 (HTTP)
   -p7687:7687 \                       # forward port 7687 (Bolt)
   -d \                                # run in background
   -e NEO4J_AUTH=neo4j/secretgraph \   # set login credentials
   neo4j:latest

Alternatively, you can obtain a free cloud instance through Aura.

You can also install Neo4j on your system, or use Neo4j Desktop to create a local development environment (not for production).

Glossary

LTS: A Long Term Support release is one guaranteed to be supported for a number of years. Neo4j 4.4 is LTS, and Neo4j 5 will also have an LTS version.
Aura: Aura is Neo4j’s fully managed cloud service. It comes with both free and paid plans.
Cypher: Cypher is Neo4j’s graph query language that lets you retrieve data from the database. It is like SQL, but for graphs.
APOC: Awesome Procedures On Cypher (APOC) is a library of (many) functions that can not be easily expressed in Cypher itself.
Bolt: Bolt is the protocol used for interaction between Neo4j instances and drivers. It listens on port 7687 by default.
ACID: Atomicity, Consistency, Isolation, Durability (ACID) are properties guaranteeing that database transactions are processed reliably. An ACID-compliant DBMS ensures that the data in the database remains accurate and consistent despite failures.
eventual consistency: A database is eventually consistent if it provides the guarantee that all cluster members will, at some point in time, store the latest version of the data.
causal consistency: A database is causally consistent if read and write queries are seen by every member of the cluster in the same order. This is stronger than eventual consistency.
NULL: The null marker is not a type but a placeholder for absence of value. For more information, see Cypher → Working with null.
transaction: A transaction is a unit of work that is either committed in its entirety or rolled back on failure. An example is a bank transfer: it involves multiple steps, but they must all succeed or be reverted, to avoid money being subtracted from one account but not added to the other.
backpressure: Backpressure is a force opposing the flow of data. It ensures that the client is not being overwhelmed by data faster than it can handle.
transaction function: A transaction function is a callback executed by an execute_read or execute_write call. The driver automatically re-executes the callback in case of server failure.
Driver: A Driver object holds the details required to establish connections with a Neo4j database.