Installation

APOC is packaged with Neo4j and can be found in the $NEO4J_HOME/labs directory.

APOC

APOC can be installed by moving the APOC jar file from the $NEO4J_HOME/labs directory to the $NEO4J_HOME/plugins directory and restarting Neo4j.

Neo4j Desktop

APOC can be installed with Neo4j Desktop, after creating your database, by going to the Manage screen, and then the Plugins tab. Click Install in the APOC box and wait until you see a green check mark near "APOC".

desktop apoc

Neo4j Server

Since APOC relies on Neo4j’s internal APIs you need to use the matching APOC version for your Neo4j installation. Make sure that the first two version numbers match between Neo4j and APOC.

Go to the latest release for Neo4j 5.26 and download the binary jar to place into your $NEO4J_HOME/plugins folder.

You can find all releases here.

After you move the jar file to the plugins folder you have to restart neo4j with neo4j restart

APOC uses a consistent versioning scheme: <neo4j-version>.<apoc> version. The trailing <apoc> part of the version number will be incremented with every apoc release.

The version compatibility matrix explains the mapping between Neo4j and APOC versions:

APOC version Neo4j version

5.25.1

5.25.1 (5.25.x)

5.24.0

5.24.0 (5.24.x)

5.23.0

5.23.0 (5.23.x)

5.22.0

5.22.0 (5.22.x)

5.21.0

5.21.0 (5.21.x)

5.20.0

5.20.0 (5.20.x)

5.19.0

5.19.0 (5.19.x)

5.18.0

5.18.0 (5.18.x)

5.17.1

5.17.0 (5.17.x)

5.16.1

5.16.0 (5.16.x)

5.15.1

5.15.0 (5.15.x)

5.14.0

5.14.0 (5.14.x)

5.13.0

5.13.0 (5.13.x)

5.12.0

5.12.0 (5.12.x)

5.11.0

5.11.0 (5.11.x)

5.10.1

5.10.0 (5.10.x)

5.9.0

5.9.0 (5.9.x)

5.8.0

5.8.0 (5.8.x)

5.7.0

5.7.0 (5.7.x)

5.6.0

5.6.0 (5.6.x)

5.5.0

5.5.0 (5.5.x)

5.4.1

5.4.0 (5.4.x)

5.3.0

5.3.0 (5.3.x)

5.2.1

5.2.0 (5.2.x)

5.1.0

5.1.0 (5.1.x)

5.0.0

5.0.0 (5.0.x)

4.4.0.24

4.4.0 (4.4.x)

If the APOC jar detected on start up is not compatible with the Neo4j version, then a log.warn warning like this will appear in neo4j.log:

The apoc version (<APOC_VERSION>) and the Neo4j DBMS versions [NEO4J_VERSION] are incompatible.
The two first numbers of both versions must be the same.

Docker

APOC can be used with the Neo4j Docker image via the NEO4J_PLUGINS environment variable. If this environment variable is used, the APOC plugin file will be copied from the Docker image and configured at runtime.

This feature is intended to facilitate using APOC in development environments, but it is not recommended for use in production environments.
The following runs Neo4j 5.26.0 in a Docker container with the latest version of the APOC Library
docker run \
    -p 7474:7474 -p 7687:7687 \
    --name neo4j-apoc \
    -e NEO4J_apoc_export_file_enabled=true \
    -e NEO4J_apoc_import_file_enabled=true \
    -e NEO4J_apoc_import_file_use__neo4j__config=true \
    -e NEO4J_PLUGINS=\[\"apoc\"\] \
    neo4j:5.26.0

We should see the following two lines in the output after running this command:

Fetching versions.json for Plugin 'apoc' from https://neo4j.github.io/apoc/versions.json
Installing Plugin 'apoc' from https://github.com/neo4j/apoc/releases/download/5.25.1/apoc-5.25.1-core.jar to /plugins/apoc.jar

In a production environment we should download the APOC release matching our Neo4j version and, copy it to a local folder, and supply it as a data volume mounted at /plugins.

The following downloads the APOC Library into the plugins directory and then mounts that folder to the Neo4j Docker container
mkdir plugins
pushd plugins
wget https://github.com/neo4j/apoc/releases/download/5.25.1/apoc-5.25.1-core.jar
popd
docker run --rm -e NEO4J_AUTH=none -p 7474:7474 -v $PWD/plugins:/plugins -p 7687:7687 neo4j:5.26.0

If you want to pass custom apoc config to your Docker instance, you can use environment variables, like here:

docker run \
    -p 7474:7474 -p 7687:7687 \
    -v $PWD/data:/data -v $PWD/plugins:/plugins \
    --name neo4j-apoc \
    -e NEO4J_apoc_export_file_enabled=true \
    -e NEO4J_apoc_import_file_enabled=true \
    -e NEO4J_apoc_import_file_use__neo4j__config=true \
    neo4j:5.26.0

Load and Unrestrict

The APOC library contains hundreds of procedures and functions. It is not recommended to load all of these into the dbms, but instead use the principle of least privilege. This principle dictates that only the procedures and functions necessary to execute the user’s workload should be loaded.

The procedures and functions that should be loaded can be specified using the database configuration setting dbms.security.procedures.allowlist located in the conf/neo4j.conf file. For example, to load apoc.math.maxInt and all functions in the apoc.rel package, use:

  • dbms.security.procedures.allowlist=apoc.math.maxInt,apoc.rel.*.

The default value of dbms.security.procedures.allowlist is to load all procedures and functions. It is therefore recommended to override the setting with a minimum list of procedures required. If no APOC functionality is required, then it is recommended to remove the APOC plugin altogether.

For security reasons, procedures and functions that use internal APIs are disabled by default. In this case, it is also recommended to use the principle of least privilege and to only unrestrict those procedures and functions which are certain to be used.

The procedures and functions that should be unrestricted can be specified using the database configuration setting dbms.security.procedures.unrestricted located in the conf/neo4j.conf file. For example, to unrestrict apoc.cypher.runFirstColumn and all procedures and functions in the apoc.cypher package, use:

  • dbms.security.procedures.unrestricted=apoc.cypher.runFirstColumn,apoc.cypher.*.

To unrestrict a whole package of APOC procedures and functions when using the Neo4j Docker container, it is possible to do so via environment variables. For example, to load all functions in the apoc.cypher package, users must add the following argument to the Docker run command:

  • -e NEO4J_dbms_security_procedures_unrestricted="apoc.cypher.*"

More information about loading and unrestricting procedures and functions can be found in the Neo4j Securing Extensions guidelines.

Additional Dependencies

Some functionalities require additional jars in order to be used. This includes loading and exporting data when using services such as:

  • Amazon S3 (s3://<path>)

  • Apache Hadoop (hdfs://<path>)

  • Google Cloud Storage (gs://<path>)

These dependencies are specifically not included in the APOC Core jar, but can be added as separate jars as described here. If the extra dependencies are not included, warnings will show in the debug log file (debug.log) that can be ignored if the respective functionality is not needed. An example of such a warning would be:

 Failed to load `apoc.util.s3.S3URLConnection`