Building from Source

How to build Deeplearning4j from source — prerequisites, Maven build, libnd4j compilation, and common build issues

Most users should use the releases on Maven Central and do not need to build from source. Building from source is intended for contributors, those testing unreleased features, or teams maintaining a custom fork. Custom layers, loss functions, and activation functions can all be added without modifying DL4J directly.

Overview

The DL4J stack is a monorepo at github.com/eclipse/deeplearning4j. A full source build produces the following components:

• libnd4j — native C++ backend (compiled with CMake)

• nd4j — Java bindings and math backend

• datavec — data pipeline and ETL

• deeplearning4j — neural network training framework and utilities

Prerequisites

Required Tools

Tool	Minimum Version	Notes
JDK	11	JDK 17 recommended for M2.1
Maven	3.6.3	Earlier 3.x releases have known issues with the monorepo
Git	2.x	Any recent version
CMake	3.9	Required to compile libnd4j
gcc / g++	7.x	Clang is not supported on Linux

Platform-Specific Setup

Linux (Ubuntu / Debian)

sudo apt-get update
sudo apt-get install -y \
    build-essential cmake git \
    libgomp1 openjdk-17-jdk maven

Verify versions before proceeding:

java -version
mvn -version
cmake --version
gcc --version

Linux (CentOS / RHEL)

sudo yum groupinstall 'Development Tools'
sudo yum install cmake3 java-17-openjdk-devel maven

macOS

Install Xcode command-line tools and Homebrew, then:

xcode-select --install
brew update
brew install cmake maven openjdk@17

Note: The system clang is used on macOS for the JNI layer, but libnd4j's native C++ code requires GCC. Install GCC via Homebrew if needed:

brew install gcc

Windows

libnd4j requires a Unix-compatible toolchain. Install MSYS2 and then run inside the MSYS2 shell:

pacman -S \
    mingw-w64-x86_64-gcc \
    mingw-w64-x86_64-cmake \
    mingw-w64-x86_64-extra-cmake-modules \
    make pkg-config grep sed gzip tar \
    mingw64/mingw-w64-x86_64-openblas

Add C:\msys64\mingw64\bin to your system PATH. Restart any open IDE after doing so.

CPU Math Libraries

Choose one of the following for CPU computation:

OpenBLAS (recommended, open source):

# Ubuntu/Debian
sudo apt-get install libopenblas-dev

# macOS
brew install openblas

# Windows (via MSYS2)
pacman -S mingw64/mingw-w64-x86_64-openblas

Intel MKL (best single-machine CPU performance): Download from Intel's developer site. After installation, add the MKL library directory to LD_LIBRARY_PATH (Linux) or PATH (Windows).

To link MKL at runtime against an OpenBLAS-linked binary, create symbolic links:

# Linux example
ln -s libmkl_rt.so libopenblas.so.0
ln -s libmkl_rt.so libblas.so.3
export MKL_THREADING_LAYER=GNU
export LD_PRELOAD=/lib64/libgomp.so.1

Cloning the Repository

git clone https://github.com/eclipse/deeplearning4j.git
cd deeplearning4j

To work on a specific release tag (for example, the M2.1 tag):

git checkout deeplearning4j-2.1.0

Building libnd4j (Native Backend)

libnd4j is the C++ compute engine. It must be compiled before the Java modules can be built.

cd libnd4j
./buildnativeoperations.sh

After compilation, export the path so Maven can locate the native libraries:

export LIBND4J_HOME=$(pwd)
cd ..

Common libnd4j Build Flags

Flag	Description
-c cuda	Build with CUDA GPU support
-cc <arch>	Target a specific CUDA compute capability (e.g., -cc 86 for Ampere)
-j <n>	Use n parallel compiler jobs
--build-type Release	Release build (default); use Debug for debugging

Example for CUDA with compute capability 8.6 (RTX 30xx):

./buildnativeoperations.sh -c cuda -cc 86 -j 8

Building with CUDA

Prerequisites

• NVIDIA CUDA Toolkit 11.x or 12.x (M2.1 supports both)

• A supported NVIDIA GPU driver

• On Windows: Visual Studio 2019 or 2022 (Community edition is sufficient)

Install CUDA from developer.nvidia.com/cuda-downloads.

Linux / macOS Build

cd libnd4j
./buildnativeoperations.sh -c cuda -cc INSERT_YOUR_DEVICE_ARCH
export LIBND4J_HOME=$(pwd)
cd ..

mvn clean install -DskipTests -Dmaven.javadoc.skip=true

Find your GPU's compute capability at developer.nvidia.com/cuda-gpus. For example, an RTX 4090 uses -cc 89.

Windows Build

1. Open a standard cmd.exe prompt and run:

   "C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvars64.bat"

2. From that same prompt, launch the MSYS2 shell:

   c:\msys64\mingw64_shell.bat

3. Inside the MSYS2 shell:

   cd /path/to/deeplearning4j/libnd4j
   ./buildnativeoperations.sh -c cuda -cc INSERT_YOUR_DEVICE_ARCH

Full Maven Build

After libnd4j is built and LIBND4J_HOME is set, build all Java modules from the repo root:

mvn clean install -DskipTests -Dmaven.javadoc.skip=true

This installs all artifacts to your local Maven repository (~/.m2/repository). A first build typically takes 15–45 minutes depending on hardware.

Building Specific Modules

Maven's -pl flag restricts the build to specific submodules:

# Build only nd4j
mvn clean install -DskipTests -pl nd4j/nd4j-backends/nd4j-backend-impls/nd4j-native

# Build only the core DL4J training module
mvn clean install -DskipTests -pl deeplearning4j/deeplearning4j-core

# Exclude CUDA modules when building without a GPU
mvn clean install -DskipTests -pl '!deeplearning4j/deeplearning4j-cuda'

Use the -am flag (--also-make) to include transitive dependencies of a module:

mvn clean install -DskipTests -pl deeplearning4j/deeplearning4j-core -am

Using the Build Script

A convenience script is provided for building the entire stack:

# CPU build
./build-dl4j-stack.sh

# CUDA build
./build-dl4j-stack.sh -c cuda

# CUDA build targeting a specific compute capability
./build-dl4j-stack.sh -c cuda -cc 86

Running Tests

DL4J tests depend on a separate test-resources repository (~10 GB). Clone it with a shallow fetch if history is not needed:

git clone --depth 1 --branch master \
    https://github.com/deeplearning4j/dl4j-test-resources
cd dl4j-test-resources
mvn install

Run tests against the native CPU backend:

mvn clean test -P testresources,test-nd4j-native

Run tests for a single module:

mvn clean test -P testresources,test-nd4j-native \
    -pl deeplearning4j/deeplearning4j-core

IDE Setup: IntelliJ IDEA

IntelliJ IDEA is the recommended IDE.

1. Clone the repository and open it as a Maven project (File > Open, select pom.xml at the repo root).

2. Install the Lombok plugin: Settings > Plugins > search "Lombok" > Install. Without it, the IDE will show false errors throughout the codebase.

3. Enable annotation processing: Settings > Build, Execution, Deployment > Compiler > Annotation Processors > check "Enable annotation processing".

4. Import Maven profiles as needed for your backend (e.g., native or cuda).

5. If working on the Scala API or the DL4J UI, install the Scala plugin.

For large monorepo projects, increase IntelliJ's JVM heap: Help > Change Memory Settings > set 4096 MB or higher.

Using Local Build Artifacts

After a successful build, use the local snapshot in a downstream project by matching the version in your pom.xml:

<dependency>
    <groupId>org.deeplearning4j</groupId>
    <artifactId>deeplearning4j-core</artifactId>
    <version>2.1.0-SNAPSHOT</version>
</dependency>

Check the current snapshot version in the root POM.

Common Build Issues

LIBND4J_HOME not set

Symptom: Maven build fails with errors about missing native libraries or JNI classes.

Fix: Export the variable pointing to the compiled libnd4j directory:

export LIBND4J_HOME=/path/to/deeplearning4j/libnd4j

CMake version too old

Symptom: cmake: command not found or CMake policy errors.

Fix: Install CMake 3.9 or newer. On older Ubuntu/CentOS systems, install via pip install cmake or download from cmake.org.

clang used instead of gcc on macOS

Symptom: Linker errors or missing OpenMP support.

Fix: Force GCC explicitly:

export CC=$(brew --prefix gcc)/bin/gcc-13
export CXX=$(brew --prefix gcc)/bin/g++-13
./buildnativeoperations.sh

Out-of-memory during Maven build

Symptom: Build fails with java.lang.OutOfMemoryError or GC overhead limit exceeded.

Fix:

export MAVEN_OPTS="-Xmx4g -XX:MaxMetaspaceSize=1g"

CUDA version mismatch

Symptom: Errors like no kernel image is available for execution on the device.

Fix: Ensure the -cc flag matches your GPU's actual compute capability. Check it with:

nvidia-smi --query-gpu=compute_cap --format=csv,noheader

Windows: DLL not found at runtime

Symptom: Can't find dependent libraries when launching from an IDE.

Fix: Add C:\msys64\mingw64\bin to your system PATH and restart the IDE.

Support

If you encounter build issues not covered here, please reach out on the DL4J GitHub Discussions or the community Gitter channel.