Docker-specific operations

You can use the Neo4j tools when running Neo4j in a Docker container.

Use Neo4j Admin

The neo4j-admin CLI can be run locally within a container using the following command:

docker exec --interactive --tty <containerID/name> neo4j-admin <category> <command>

To determine the container ID or name, run docker ps to list the currently running Docker containers.

For more information about the neo4j-admin commands, see Neo4j Admin and Neo4j CLI.

Use Neo4j Import

The Neo4j Import tool can be run locally within a container using the following commands:

docker exec --interactive --tty <containerID/name> neo4j-admin database import full <options>

and

docker exec --interactive --tty <containerID/name> neo4j-admin database import incremental <options>

For more information about the commands' syntax and options, see Full import and Incremental import.

Prerequisites

  • Verify that you have created the folders that you want to mount as volumes to the Neo4j docker container.

  • Verify that the CSV files that you want to load into Neo4j are formatted as per CSV header format.

  • Verify that you have added the CSV files to the folder that will be mounted to /import in your container.

Import CSV files into the Neo4j Docker container using the Neo4j import tool

This is an example of how to start a container with mounted volumes /data and /import, to ensure the persistence of the data in them, and load the CSV files using the neo4j-admin database import full command. You can add the flag --rm to automatically remove the container’s file system when the container exits.

docker run --interactive --tty --rm \
    --publish=7474:7474 --publish=7687:7687 \
    --volume=$HOME/neo4j/data:/data \
    --volume=$HOME/neo4j/import:/import \
    neo4j:2025.06.0 \
neo4j-admin database import full --nodes=Movies=/import/movies_header.csv,/import/movies.csv \
--nodes=Actors=/import/actors_header.csv,/import/actors.csv \
--relationships=ACTED_IN=/import/roles_header.csv,/import/roles.csv databasename

Use Neo4j Admin for memory recommendations

The neo4j-admin server memory-recommendation command with the argument --docker outputs environmental variables that can be passed to a Neo4j docker container. The following example shows how neo4j-admin server memory-recommendation --docker provides a memory recommendation in a docker-friendly format.

Example 1. Invoke neo4j-admin server memory-recommendation --docker
bin/neo4j-admin server memory-recommendation --memory=16g --docker

...
...
...
# Based on the above, the following memory settings are recommended:
NEO4J_server_memory_heap_initial__size='5g'
NEO4J_server_memory_heap_max__size='5g'
NEO4J_server_memory_pagecache_size='7g'
#
# It is also recommended turning out-of-memory errors into full crashes,
# instead of allowing a partially crashed database to continue running:
NEO4J_server_jvm_additional='-XX:+ExitOnOutOfMemoryError'
#
...
...

Use Neo4j Admin report

The Neo4j Admin report tool generates a report of the status of a running Neo4j database.
In a containerized environment, its command neo4j-admin server report must be invoked using the script neo4j-admin-report. This ensures that the reporter is running with all the necessary file permissions required to analyze the running Neo4j processes. This script takes all the arguments of the neo4j-admin server report command.

It is possible to use docker exec to run neo4j-admin server report directly inside the container, but the file permissions required to access running processes and to write files to a mounted folder can be conflicting.

The neo4j-admin-report script is just a wrapper around neo4j-admin server report which automatically handles most permission problems.
Example 2. Example of getting a Neo4j report from a containerised Neo4j database

Start a Neo4j container and mount a folder for storing the reports.

docker run --interactive --tty --rm \
    --name=neo4j \
    --publish=7474:7474 --publish=7687:7687 \
    --volume=$HOME/neo4j/data:/data \
    --volume=$HOME/neo4j/reports:/reports \ (1)
    neo4j:2025.06.0
1 The output folder for the reports.

Then, using docker exec, run the neo4j-admin-report wrapper script, specifying the output directory for the reports.

docker exec --interactive --tty <containerID/name> \
    neo4j-admin-report \
        --to-path=/reports \ (1)
1 If no --to-path option is specified, the reports will be written to /tmp/reports.

The $HOME/neo4j/reports folder should now contain a zip file of reports.

Use Cypher Shell

The Cypher Shell can be run locally within a container using the following command:

docker exec --interactive --tty <containerID/name> cypher-shell <options>

For more information about the cypher-shell syntax and options, see Cypher Shell#cypher-shell-syntax[Syntax].

Retrieve data from a database in a Neo4j Docker container

The following is an example of how to use the cypher-shell command to retrieve data from the neo4j database.

  1. Run a new container, mounting the same volume /data as in the import example.

    docker run --interactive --tty --name <containerID/name> \
    --publish=7474:7474 --publish=7687:7687 \
    --volume=$HOME/neo4j/data:/data \
    neo4j:2025.06.0

  2. Use the container ID or name to get into the container, and then, run the cypher-shell command and authenticate.

    docker exec --interactive --tty <containerID/name> cypher-shell -u neo4j -p <password>

  3. Retrieve some data.

    neo4j@neo4j> match (n:Actors)-[r]->(m:Movies) return n.name AS Actors, m.title AS Movies, m.year AS MovieYear;
+-------------------------------------------------------------+
| Actors               | Movies                   | MovieYear |
+-------------------------------------------------------------+
| "Keanu Reeves"       | "The Matrix Revolutions" | 2003      |
| "Keanu Reeves"       | "The Matrix Reloaded"    | 2003      |
| "Keanu Reeves"       | "The Matrix"             | 1999      |
| "Laurence Fishburne" | "The Matrix Revolutions" | 2003      |
| "Laurence Fishburne" | "The Matrix Reloaded"    | 2003      |
| "Laurence Fishburne" | "The Matrix"             | 1999      |
| "Carrie-Anne Moss"   | "The Matrix Revolutions" | 2003      |
| "Carrie-Anne Moss"   | "The Matrix Reloaded"    | 2003      |
| "Carrie-Anne Moss"   | "The Matrix"             | 1999      |
+-------------------------------------------------------------+

9 rows available after 61 ms, consumed after another 7 ms

Pass a Cypher script file to a Neo4j Docker container

There are different ways to pass a Cypher script file to a Neo4j Docker container, all of them using the Cypher Shell tool.

  • Using the --file option of the cypher-shell command followed by the file name. After the statements are executed cypher-shell shuts down.

  • Using the :source command followed by the file name when in the Cypher interactive shell.

  • Using the commands cat or curl with cypher-shell to pipe the contents of your script file into your container.

To use the --file option or the :source command of Cypher Shell, the Cypher script file must be readable from inside the container, otherwise cypher-shell will not be able to open the file. The folder containing the examples must be mounted to the container when the container is started.

The following are syntax examples of how to use these commands:

example.cypher script
match (n:Actors)-[r]->(m:Movies) return n.name AS Actors, m.title AS Movies, m.year AS MovieYear;
Invoke cypher-shell with the --file option
# Put the example.cypher file in the local folder ./examples.

# Start a Neo4j container and mount the ./examples folder inside the container:

docker run --rm \
--volume /path/to/local/examples:/examples \
--publish=7474:7474 \
--publish=7687:7687 \
--env NEO4J_AUTH=neo4j/your_password \
neo4j:2025.06.0

# Run the Cypher Shell tool with the --file option passing the example.cypher file:

docker exec --interactive --tty  cypher-shell -u neo4j -p  --file /examples/example.cypher
Use the :source command to run a Cypher script file
# Put the example.cypher file in the local folder ./examples.

# Start a Neo4j container and mount the ./examples folder inside the container:

docker run --rm \
--volume /path/to/local/examples:/examples \
--publish=7474:7474 \
--publish=7687:7687 \
--env NEO4J_AUTH=neo4j/your_password \
neo4j:2025.06.0

# Use the container ID or name to get into the container, and then, run the cypher-shell command and authenticate.

docker exec --interactive --tty  cypher-shell -u neo4j -p 

# Invoke the :source command followed by the file name.

neo4j@neo4j> :source example.cypher
Invoke curl with Cypher Shell
curl http://mysite.com/config/example.cypher | sudo docker exec --interactive <containerID/name> cypher-shell -u neo4j -p <password>
Invoke cat with Cypher Shell
cat example.cypher | sudo  docker exec --interactive  <containerID/name> cypher-shell -u neo4j -p <password>
Example output
Actors, Movies, MovieYear
"Keanu Reeves", "The Matrix Revolutions", 2003
"Keanu Reeves", "The Matrix Reloaded", 2003
"Keanu Reeves", "The Matrix", 1999
"Laurence Fishburne", "The Matrix Revolutions", 2003
"Laurence Fishburne", "The Matrix Reloaded", 2003
"Laurence Fishburne", "The Matrix", 1999
"Carrie-Anne Moss", "The Matrix Revolutions", 2003
"Carrie-Anne Moss", "The Matrix Reloaded", 2003
"Carrie-Anne Moss", "The Matrix", 1999

These commands take the contents of the script file and pass it into the Docker container using Cypher Shell. Then, they run a Cypher example, LOAD CSV dataset, which might be hosted somewhere on a server (with curl), create indexes, constraints, or do other administrative operations.