> For the complete documentation index, see [llms.txt](https://deeplearning4j.konduit.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://deeplearning4j.konduit.ai/deeplearning4j/build-from-source.md).

# Building from Source

> **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](https://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)**

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

Verify versions before proceeding:

```bash
java -version
mvn -version
cmake --version
gcc --version
```

**Linux (CentOS / RHEL)**

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

**macOS**

Install Xcode command-line tools and [Homebrew](https://brew.sh/), then:

```bash
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:

```bash
brew install gcc
```

**Windows**

libnd4j requires a Unix-compatible toolchain. Install [MSYS2](https://www.msys2.org/) and then run inside the MSYS2 shell:

```bash
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):

```bash
# 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](https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html). 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:

```bash
# 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

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

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

```bash
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.

```bash
cd libnd4j
./buildnativeoperations.sh
```

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

```bash
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):

```bash
./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](https://developer.nvidia.com/cuda-downloads).

#### Linux / macOS Build

```bash
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](https://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:

   ```bash
   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:

```bash
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:

```bash
# 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:

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

#### Using the Build Script

A convenience script is provided for building the entire stack:

```bash
# 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:

```bash
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:

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

Run tests for a single module:

```bash
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`:

```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](https://github.com/eclipse/deeplearning4j/blob/master/pom.xml).

### 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:

```bash
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](https://cmake.org/download/).

#### `clang` used instead of `gcc` on macOS

**Symptom:** Linker errors or missing OpenMP support.

**Fix:** Force GCC explicitly:

```bash
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:**

```bash
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:

```bash
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](https://github.com/eclipse/deeplearning4j/discussions) or the community [Gitter channel](https://gitter.im/deeplearning4j/deeplearning4j).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://deeplearning4j.konduit.ai/deeplearning4j/build-from-source.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.