Ctrlk
Community ForumND4J JavadocDL4J Javadoc
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Maven Setup

Maven dependencies for Deeplearning4j — BOM, backend selection, platform classifiers, and version management

Overview

Maven is the recommended build tool for Deeplearning4j projects. DL4J and ND4J publish a bill of materials (BOM) that makes version management straightforward, and platform-specific classifiers that bundle native binaries for all major operating systems in a single dependency.

This page covers the full Maven setup: BOM usage, core dependencies, backend selection, GPU dependencies, a complete example pom.xml, the classifier system, and how to resolve version conflicts.

Using the DL4J BOM (Bill of Materials)

The BOM centralizes version management so you only specify the DL4J version in one place. Import it in the <dependencyManagement> section of your pom.xml:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.eclipse.deeplearning4j</groupId>
            <artifactId>deeplearning4j-bom</artifactId>
            <version>1.0.0-rewrite</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

With the BOM in place you can declare DL4J and ND4J dependencies without repeating the version:

<dependencies>
    <dependency>
        <groupId>org.eclipse.deeplearning4j</groupId>
        <artifactId>deeplearning4j-core</artifactId>
    </dependency>
    <dependency>
        <groupId>org.eclipse.deeplearning4j</groupId>
        <artifactId>nd4j-native-platform</artifactId>
    </dependency>
</dependencies>

Core Dependencies

deeplearning4j-core

The main DL4J library. Includes MultiLayerNetwork, ComputationGraph, built-in layers, training infrastructure, and listeners.

ND4J Backend (CPU)

DL4J relies on ND4J for all tensor operations. You must add exactly one ND4J backend. For CPU:

The -platform suffix bundles native binaries for Linux x86_64, Linux ARM64, macOS x86_64, macOS ARM64 (Apple Silicon), and Windows x86_64 in one JAR. See the Platform Classifiers section for single-platform alternatives.

GPU Dependencies

ND4J CUDA Backend

To run on NVIDIA GPUs, replace nd4j-native-platform with the CUDA backend:

CUDA toolkit 12.9 (or a compatible version) must be installed on the host. See the GPU/CPU Setup page for the full CUDA installation guide.

cuDNN Acceleration

To enable cuDNN for CNN and LSTM layers, add the cuDNN helper module alongside the CUDA ND4J backend:

See the cuDNN page for details.

Complete pom.xml Example

The following pom.xml is a minimal but complete starting point for a DL4J project using CPU:

Switching to GPU

To switch from CPU to GPU, replace the nd4j-native-platform dependency with:

Using a property makes this easy to switch at build time:

Platform Classifiers

DL4J's native libraries are distributed using JavaCPP platform JARs. The -platform artifact is a multi-platform convenience wrapper that pulls in native binaries for all supported platforms.

If you are building and deploying on a single OS, you can use the non-platform artifact with an explicit classifier to reduce JAR size:

Available classifiers:

Classifier
Platform

linux-x86_64

Linux 64-bit (Intel/AMD)

linux-arm64

Linux ARM 64-bit (e.g., Graviton)

macosx-x86_64

macOS Intel

macosx-arm64

macOS Apple Silicon (M1/M2/M3)

windows-x86_64

Windows 64-bit

When using classifiers for CUDA backends, you also need the CUDA-specific classifier:

Note: Snapshot builds can have transient issues with -platform artifacts when cross-platform builds are not yet synchronized. In that case, using single-platform classifiers is more reliable. See the Snapshots page for more details.

-lite Classifier (ADR 0030)

The -lite classifier produces a smaller native binary by limiting the set of data types compiled into the C++ template instantiations. The full (base) artifact supports all ND4J types — bool, int8, uint8, int16, uint16, int32, uint32, int64, uint64, float16, bfloat16, float32, double. The -lite artifact compiles only the types your deployment actually needs, reducing binary size and build time.

When to Use -lite

Use the -lite artifact when:

  • Deploying to edge or mobile environments where storage or bandwidth is constrained (e.g., Android, IoT devices, Docker images with strict size budgets).

  • Your model exclusively uses a narrow type set — for example, FP32 inference with INT8 quantized weights, or BF16 training with no need for double or legacy integer types.

  • You want faster build pipelines — fewer template instantiations means faster native compilation for local development on resource-limited CI machines.

Avoid -lite when:

  • Your application mixes a wide variety of data types at runtime (mixed-precision training across float16, bfloat16, and float32 simultaneously).

  • You rely on type promotion across integer and floating-point types (the full type-rank system is only guaranteed complete in the base artifact).

  • You are unsure which types your model uses — start with the base artifact and switch to -lite once you have confirmed your type requirements.

Comparison: Base vs. -lite vs. -compile

Artifact
Type Coverage
JIT Compilation
Binary Size
Best For

Base (no suffix)

All ND4J types

No (CUDA graphs / slot-by-slot)

Medium

General-purpose, dev/testing

-lite

Reduced type set

No

Small

Edge/mobile, single-type workloads

-compile

All ND4J types

Yes (Triton, NVRTC, MLIR)

Large

LLM inference, maximum throughput

Maven Setup

With the -platform artifact, steer JavaCPP to the lite variant at runtime:

If a type that was excluded from the -lite build is requested at runtime, ND4J throws an UnsupportedTypeException with a message indicating which type is absent and which artifact to use instead.

DSP JIT Classifier (-compile)

The 1.0.0-rewrite release introduces a -compile classifier variant for each platform. This variant bundles the DSP (Dynamic Shape Plan) JIT compilation stack — Triton, NVRTC, PTX, and MLIR — into the native binary. The base classifier (without -compile) includes standard ops and CUDA graph capture/replay but does not include JIT kernel fusion.

When to use -compile: Use it when running transformer models or LLMs where kernel fusion and JIT compilation deliver significant latency improvements. The trade-off is a larger binary with more native dependencies.

When to use the base classifier: Use it for simpler workloads, resource-constrained deployments, or when binary size matters more than maximum JIT performance.

Maven Setup for -compile

Explicit classifier:

With -platform artifact (select at runtime):

See Hardware Backends — Classifier Variants for available classifiers and a decision guide.

Additional Modules

Beyond the core, DL4J has several optional modules:

Resolving Version Conflicts

DL4J pulls in several transitive dependencies — notably JavaCPP, OpenBLAS, and various BLAS implementations. If other libraries in your project use incompatible versions of these, Maven's dependency mediation rules (nearest-wins) may choose the wrong version.

Symptoms of version conflicts

  • UnsatisfiedLinkError when loading native libraries

  • NoSuchMethodError from ND4J or JavaCPP classes

  • Silent use of wrong backend (e.g., CPU when GPU expected)

Diagnosing conflicts

Run Maven's dependency tree to inspect resolved versions:

Forcing consistent versions with the BOM

The DL4J BOM pins the versions of all ND4J and JavaCPP artifacts. Importing it (as shown above) is the most reliable way to avoid conflicts. If you must exclude a transitive dependency and pin it yourself:

Excluding conflicting transitive dependencies

If a third-party library brings in an old version of a shared dependency, exclude it explicitly:

Java Version Requirements

DL4J 1.0.0-rewrite requires Java 11 or later. Java 17 is supported. Set the compiler plugin accordingly:

Related Pages

PreviousAvailable Models
NextBuild Tools (Gradle, SBT)

Last updated

Was this helpful?