Chapter 2. Installation

This chapter provides instructions for installation and basic usage of the Neo4j Graph Data Science library.

The Neo4j Graph Data Science (GDS) library is delivered as a plugin to the Neo4j Graph Database. The plugin needs to be installed into the database and whitelisted in the Neo4j configuration. There are two main ways of achieving this, which we will detail in this chapter.

2.1. Supported Neo4j versions

The GDS library supports the following Neo4j versions:

Neo4j Graph Data Science Neo4j version


4.1.0 - 4.1.3

4.0.0 - 4.0.8

1.2.3 [a]

4.0.0 - 4.0.6

1.2.0 - 1.2.2 [a]

4.0.0 - 4.0.4


3.5.9 - 3.5.22

1.0.x [a]

3.5.9 - 3.5.18

[a] This version series is end-of-life and will not receive further patches. Please use a later version.

2.2. Neo4j Desktop

The most convenient way of installing the GDS library is through the Neo4j Desktop plugin called Neo4j Graph Data Science. The plugin can be found in the 'Plugins' tab of a database.

neo4j desktop gds

The installer will download the GDS library and install it in the 'plugins' directory of the database. It will also add the following entry to the settings file:*

This configuration entry is necessary because the GDS library accesses low-level components of Neo4j to maximise performance.

If the procedure whitelist is configured, make sure to also include procedures from the GDS library:*

2.3. Neo4j Server

The GDS library is intended to be used on a standalone Neo4j server.

Running the GDS library in a Neo4j Causal Cluster is not supported. Read more about how to use GDS in conjunction with Neo4j Causal Cluster deployment below.

On a standalone Neo4j Server, the library will need to be installed and configured manually.

  1. Download neo4j-graph-data-science-[version]-standalone.jar from the Neo4j Download Center and copy it into the $NEO4J_HOME/plugins directory.
  2. Add the following to your $NEO4J_HOME/conf/neo4j.conf file:*

    This configuration entry is necessary because the GDS library accesses low-level components of Neo4j to maximise performance.

  3. Check if the procedure whitelist is enabled in the $NEO4J_HOME/conf/neo4j.conf file and add the GDS library if necessary:*
  4. Restart Neo4j

2.3.1. Verifying installation

To verify your installation, the library version can be printed by entering into the browser in Neo4j Desktop and calling the gds.version() function:

RETURN gds.version()

To list all installed algorithms, run the gds.list() procedure:

CALL gds.list()

2.4. Neo4j Causal Cluster

A Neo4j Causal Cluster consists of multiple machines that together support a highly available database management system. The GDS library uses main memory on a single machine for hosting graphs in the graph catalog and computing algorithms over these. These two architectures are not compatible and should not be used in conjunction. A GDS workload will attempt to consume most of the system resources of the machine during runtime, which may make the machine unresponsive for extended periods of time. For these reasons, we strongly advise against running GDS in a cluster as this potentially leads to data corruption or cluster outage.

To make use of GDS on graphs hosted by a Neo4j Causal Cluster deployment, these graphs should be detached from the running cluster. This can be accomplished in several ways, including:

  1. Dumping a snapshot of the Neo4j store and importing it in a separate standalone Neo4j server.
  2. Adding a Read Replica to the Neo4j Causal Cluster and then detaching it to safely operate GDS on a snapshot in separation from the Neo4j Causal Cluster.
  3. Adding a Read Replica to the Neo4j Causal Cluster and configuring it for GDS workloads, which requires:

    • installing GDS on the Read Replica
    • managing cluster synchronisation events during GDS algorithm execution
    • avoiding use of GDS write-back features
    • consuming results from GDS workloads directly via Cypher

After the GDS workload has finished on a detached machine (for cases 1. and 2.) it now contains out-of-sync results written to its copied version of the graph from the Neo4j Causal Cluster. To integrate these results back to the cluster, custom programs are necessary.

2.5. System Requirements

2.5.1. Main Memory

The GDS library runs within a Neo4j instance and is therefore subject to the general Neo4j memory configuration.

Figure 2.1. GDS heap memory usage
memory usage Heap size

The heap space is used for storing graph projections in the graph catalog and algorithm state. When writing algorithm results back to Neo4j, heap space is also used for handling transaction state (see dbms.tx_state.memory_allocation). For purely analytical workloads, a general recommendation is to set the heap space to about 90% of the available main memory. This can be done via dbms.memory.heap.initial_size and dbms.memory.heap.max_size.

To better estimate the heap space required to create in-memory graphs and run algorithms, consider the Section 3.1, “Memory Estimation” feature. The feature estimates the memory consumption of all involved data structures using information about number of nodes and relationships from the Neo4j count store. Page cache

The page cache is used to cache the Neo4j data and will help to avoid costly disk access.

For purely analytical workloads using native projections, it is recommended to decrease dbms.memory.pagecache.size in favor of an increased heap size. However, setting a minimum page cache size is still important while creating in-memory graphs:

  • For native projections, the minimum page cache size for creating the in-memory graph can be roughly estimated by 8KB * 100 * readConcurrency.
  • For Cypher projections, a higher page cache is required depending on the query complexity.

However, if it is required to write algorithm results back to Neo4j, the write performance is highly depended on store fragmentation as well as the number of properties and relationships to write. We recommend starting with a page cache size of roughly 250MB * writeConcurrency and evaluate write performance and adapt accordingly. Ideally, if the memory estimation feature has been used to find a good heap size, the remaining memory can be used for page cache and OS.

Decreasing the page cache size in favor of heap size is not recommended if the Neo4j instance runs both, operational and analytical workloads at the same time. See Neo4j memory configuration for general information about page cache sizing.

2.5.2. CPU

The library uses multiple CPU cores for graph projections, algorithm computation, and results writing. Configuring the workloads to make best use of the available CPU cores in your system is important to achieve maximum performance. The concurrency used for the stages of projection, computation and writing is configured per algorithm execution, see Section 5.1.1, “Configuration parameters”

The maximum concurrency that can be used is limited depending on the license under which the library is being used:

  • Neo4j Community Edition

    • The maximum concurrency in the library is 4.
  • Neo4j Enterprise Edition

    • The maximum concurrency in the library is 4.
  • Neo4j Graph Data Science Library - Enterprise Edition