Introducing Neo4j 5: Unbounded Scale, Performance, and Agility | Learn More

Online Course Basic Neo4j 4.0 Administration Introduction to Neo4j Overview of Neo4j Administration Managing a Neo4j Instance Using cypher-shell to Manage Databases Copying Databases Changing the Database Location Checking Database Consistency Scripting to Manage Databases Configuring Plugins Managing HTTP Ports… Read more →

Managing a Neo4j Instance

About this module

Next, you will learn how to perform some administrative tasks with the Neo4j instance.

At the end of this module, you should be able to:

  • Start the Neo4j instance.
  • Stop the Neo4j instance.
  • Check the status of the Neo4j instance.
  • Set the password for the neo4j user.

Neo4j instance files

Depending on your platform, a Neo4j instance’s files are, by default, placed as described here. Here is a brief overview of the default directories you will frequently use for managing the Neo4j instance in Debian.

Purpose of directory Description


The /usr/bin directory contains the tooling scripts you will typically run to manage the Neo4j instance.


neo4j.conf is the primary configuration file for the Neo4j instance and resides in the /etc/neo4j directory.


The /var/log/neo4j directory contains log files that you can monitor.


The /var/lib/neo4j/data directory contains the database(s).

Post-installation preparation

In this training, all screenshots and examples are shown using Neo4j Enterprise Edition installed as a Debian package in a Docker instance. In your real application environment, if your system is different, you will need to adjust file locations and how you manage the Neo4j instance.

When you are setting up a production environment, you want to control who can manage the Neo4j instance. You will also want to control when the Neo4j instance starts as you will be performing some configuration changes and database operations that may require that the instance to be stopped.

When Neo4j is installed as a Debian package, the neo4j service is disabled. On most platforms, the Neo4j instance is not automatically started.

Post-install: Changing the neo4j password for the Neo4j instance

After you install Neo4j and before you start the Neo4j instance, a best practice is to change the default password for the user neo4j. You do this on all platforms, except when you have installed a Debian package. You will learn about changing the neo4j password on Debian later in this module as we use Debian for this course.

On systems, other than Debian, you change the password for the neo4j user by executing the following command:

[sudo] bin/neo4j-admin set-initial-password newPassword

where newPassword is a password you will remember.

If at some point you have forgotten the admin password for your installation or you need to change it, you can reset the password by following the steps here

Post-install: Debian

Initially and only on Debian, you should disable neo4j as a service that is started automatically when the system starts. You do this with this command:

[sudo] systemctl disable neo4j

In addition, you should create the directory /var/run/neo4j that is owned by neo4j:neo4j. This is where the PID for the currently running Neo4j instance is placed.

Managing the Neo4j instance

When the instance is started (on Debian) it creates a database directory named neo4j in the default location which is a directory under /var/lib/neo4j/data/databases.

You can start and stop the instance regardless of whether the neo4j service is enabled.

Here is how you manage the Neo4j instance on Debian:

  • [sudo] systemctl start neo4j
  • [sudo] systemctl stop neo4j
  • [sudo] systemctl restart neo4j
  • systemctl status neo4j

Here is how you manage the Neo4j instance on non-Debian systems:

  • [sudo] bin/neo4j start
  • [sudo] bin/neo4j stop
  • [sudo] bin/neo4j restart
  • bin/neo4j status

When the Neo4j instance starts, it opens the databases, and writes to the directories for the databases and to the log file.

Checking the status of the instance

At any time, you can check the status of the Neo4j instance.

You check the status of the instance as follows:

systemctl status neo4j

Here is an example where we check the status of the Neo4j instance:


Here we see that the instance is started. Notice that the service is disabled as well. After the instance is started you can identify the process ID (Main PID) from the status command on Debian. It is sometimes helpful to know the process ID of the Neo4j instance (JVM) in the event that it is unresponsive and you must kill it.

However, knowing whether the instance is started (active) is generally not sufficient, especially if you have made some configuration changes. You can view details of the Neo4j instance by examining the log file.

Viewing the neo4j log

The status command gives you a short glimpse of the status of the Neo4j instance. In some cases, although the instance is active, it may not have started successfully. You may want to examine more information about the instance, such as the directories it is using at runtime and information about activity against the instance, and especially if any errors occurred during startup. As an administrator, you should become familiar with the types of records that are written to the log files for the Neo4j instance.

You can view the log file for the instance on Debian as follows:

  • journalctl -u neo4j to view the entire neo4j log file.
  • journalctl -e -u neo4j to view the end of the neo4j log file.
  • journalctl -u neo4j -b > neo4j.log where you can view neo4j.log in an editor.

Here is the result from journalctl where we want to view then end of the log file:


When the Neo4j instance starts, you can also confirm that it is started by seeing the Started record in the log file.

You can also view the log file (neo4j.log) in the logs directory on non Debian platforms. For a Docker Neo4j instance, you use the logs command which you will use in the hands-on exercises.

About the Docker Neo4j instance

When a Docker Neo4j instance is started, it is the Neo4j instance you work with. That is, you do not start and stop the Neo4j instance, but rather the Docker Neo4j instance. For all hands-on exercises of this training, you will be using the Docker Neo4j instance.

With Docker, there is no PID as there is on other systems for checking the status of the Neo4j instance. That is, systemctl status neo4j cannot be used to check the status of the Neo4j instance.

Instead, you can view the log to check the status which is what you will be doing for the hands-on exercises where we have created the Docker Neo4j instance named neo4j:

[sudo] docker logs neo4j


Exercise #2: Managing the Neo4j instance

In this Exercise, you will stop and start the Neo4j instance and view its status and log file using the Docker Neo4j instance you verified in the previous exercise.

Before you begin

Open a terminal on your system to access the Docker Neo4j instance.

Exercise steps:

  1. View the status of neo4j:
[sudo] docker logs neo4j

You should see something like this:


  1. Stop the Neo4j instance and then view its status.
[sudo] docker stop neo4j
[sudo] docker logs neo4j


  1. Examine the database directories created for this Neo4j instance.


  2. Examine the log files for this Neo4j instance.


The log files you see here are for advanced monitoring. To view the basic log file in the Docker Neo4j instance, you use the docker logs command.

Basic Docker commands

Description Docker command

[sudo] docker start <name>

Start the instance of a given name.

[sudo] docker stop <name>

Stop the instance of a given name.

[sudo] docker ps

View instances that are running.

[sudo] docker ps -a

View all instances that are running or stopped.

[sudo] docker rm <name>

Remove an instance.

Exercise summary

You have now gained experience starting and stopping a Docker Neo4j instance as well as viewing its status and the log file for the instance.

Check your understanding

Question 1

What is the name of the configuration file used by the Neo4j instance when it starts?

Select the correct answer.

  • neo4j.conf
  • neo4j-config.xml
  • neo4j-config.json

Question 2

You control the Neo4j instance by using the neo4j tool which on Debian is accessed using systemctl. What commands are available for managing the non-Docker Neo4j instance?

Select the correct answers.

  • start
  • stop
  • restart
  • reset

Question 3

On Debian, how do you determine if the Neo4j instance is started?

Select the correct answers.

  • systemctl status neo4j and look for “Started”.
  • systemctl started neo4j and look for “Started”.
  • journalctl -e -u neo4j and look for “Started”.
  • Open the neo4j.log file and view the end of the file to find “Started”.


You should now be able to:

  • Start the Neo4j instance.
  • Stop the Neo4j instance.
  • Check the status of the Neo4j instance.
  • Set the password for the neo4j user.

Stay Connected

Sign up to find out more about Neo4j's upcoming events & meetups.