This is a multistep install. We highly recommend you join our Gitter Live Chat if you have questions or feedback, so we can walk you through it. If you’re feeling anti-social or brashly independent, you’re still welcome to lurk and learn.

To get started with ND4J and DL4J, please read the following:

  1. Prerequisites
  2. Integrated Development Environment
  3. New ND4J Project
  4. Dev Tools
  5. GPUs
  6. Next Steps

ND4J is an open-source project targetting professional Java developers familiar with production deployments, an IDE like IntelliJ and an automated build tool such as Apache Maven. Our tool will serve you best if you have those tools under your belt already.

Prerequisites

System configuration requirements:

Above 0.7.2:

Optional:

JDK and Maven

For help installing the Java Development Kit or Maven, see the DL4J quickstart.

JavaCPP

JavaCPP provides efficient access to native C++ inside Java. Git clone and install when using version above 0.7.2.

BLAS

BLAS is used as a backend for libnd4j computations. You can choose between ATLAS, MKL, or OpenBLAS. Note, if you use OpenBLAS check fortran requirements and make sure to configure for the number of cores on your machine.

Integrated Development Environment: IntelliJ

An Integrated Development Environment (IDE) will allow you to work with our API and build your nets with a few clicks. We suggest using IntelliJ, which works with your installed version of Java and communicates with Maven to handle the dependencies.

The free community edition of IntelliJ has installation instructions. While we prefer that, Eclipse and Netbeans are two other popular IDEs. Here is a guide to installing the ND4J/DL4J package on Eclipse.

Starting a New ND4J Project

To create a new ND4J project within IntelliJ, either click on “Open Project” on IntelliJ’s opening screen, or click on the File/Open tab, and choose “nd4j.” If you have cloned the source files from Github, the directory should be available from IntelliJ.

To create a new ND4J project within IntelliJ, just put the right dependencies in your project’s POM.xml file. With those in place, Maven will be able to build ND4J for you. Pasting the right dependencies into your POM amounts to installing ND4J – no other install is necessary.

Select maven-archetype-quickstart.

Alt text

The images below will walk you through the windows of the IntelliJ New Project Wizard using Maven. First, name your group and artifact as you please.

Alt text

Click through the following screen with “Next”, and on the screen after that, name your project (“ND4J-test”, for example) and hit finish. Now go into your POM.xml file within the root of the new ND4J project in IntelliJ.

Update the POM file with the dependences you’ll need. These will vary depending on whether you’re running on CPUs or GPUs.

The default backend for CPUs is nd4j-native-platform, and for CUDA it is nd4j-cuda-7.5-platform. You can paste that into the <dependencies> ... </dependencies> section of your POM like this:

<dependency>
 <groupId>org.nd4j</groupId>
 <artifactId>nd4j-native-platform</artifactId>
 <version>${nd4j.version}</version>
</dependency>

ND4J’s version is a variable here. It will refer to another line higher in the POM, in the <properties> ... </properties> section, specifying the nd4j version and appearing similar to this:

<nd4j.version></nd4j.version>

The dl4j version and DataVec version are also .

Version `` or higher now includes all backends by default and binaries for all platforms are automatically pulled. It is recommended to not alter this behavior especially if you are building on one platform but deploying to another (OS X vs. Linux). However, you can also explicitly pull binaries only for the platforms you are using. Information on how to do this can be found on the dependencies page.

Other Build Systems

If you are using a build tool such as Gradle or sbt, the artifacts work in the similar ways. For example, inside a build.gradle file:

repositories {
    mavenCentral()
}
dependencies {
    compile 'org.nd4j:nd4j-native-platform:'
}

Note: if your Gradle project fails with an error like the following:

Warning:<i><b>root project 'search-classifier': Unable to resolve additional project configuration.</b>
Details: org.gradle.api.artifacts.ResolveException: Could not resolve all dependencies for configuration ':naive-classifier:compile'.
Caused by: org.gradle.internal.resolve.ArtifactNotFoundException: Could not find opencv-linux-x86.jar (org.bytedeco.javacpp-presets:opencv:3.1.0-1.3).
Searched in the following locations:
    file:/Users/user/.m2/repository/org/bytedeco/javacpp-presets/opencv/3.1.0-1.3/opencv-3.1.0-1.3-linux-x86.jar</i>

You can add the required dependencies as below. This is because Gradle has limited support for classifiers.

compile 'org.bytedeco.javacpp-presets:opencv:3.1.0-1.3'
compile 'org.bytedeco.javacpp-presets:opencv:3.1.0-1.3.3:linx-x86'

Similarly, for sbt, we need to include something like the following inside build.sbt:

classpathTypes += "maven-plugin"

libraryDependencies += "org.nd4j" % "nd4j-native-platform" % ""

Stay Up-to-date

The number of the version will vary as we progress with new releases. Make sure you check the latest version available on Maven Central. If you paste in the right dependency and ND4J version, Maven will automatically install the required libraries and you should be able to run ND4J.

Switching Backends

The backend does not have to be nd4j-native; it can be switched to Jcublas for GPUs. That’s explained on our dependencies page, alongside more advanced configuration changes. The same page also explains how to check on the latest version of the libraries.

Your Main Class

You can now create a new Java file within IntelliJ, and start using ND4J’s API for distributed linear algebra.

Open App.java file that is created with every new Intellij project, and start writing code between the curly brackets you see after public static void main( String[] args ).

Many of the classes will appear in red, since you haven’t imported the right packages, but IntelliJ will add those packages automatically to the top of your file. Lookup the appropriate hot keys based on your OS to help automatically load the packages.

(See our intro for a couple beginning operations. ND4J in IntelliJ has autocomplete, so starting a new line with any letter will show you a list of all ND4J commands including that letter.)

GitHub & Source

Github is a web-based Revision Control System, the de facto host for open-source projects.

If you are not planning to contribute to ND4J as a committer, or don’t need the latest alpha version, we recommend downloading the most recent stable release of ND4J from Maven Central. The JAR files can be downloaded directly from Maven Central. Otherwise, please see source.

Scala

While Scala doesn’t need to be installed with work with ND4J, we do have a Scala API under a repository known as ND4S.

Scala is a multiparadigm language with a strong static type system that runs on the JVM. As such, Scala has functional programming features similar to Scheme and Haskell as well as OOP features like Java, and its structure keeps programs concise. You can use Java libraries with Scala. There are neural net examples you can run written in Scala, and it’s required for the Spark implementation.

To test which version of Scala you have (and whether you have it at all), type the following into your command line:

	scala -version

To install Scala, visit the Scala download page. ND4J is compatible with Scala 2.10.4, and Scala is not backwards compatible. Homebrew will help Mac users install Scala. brew install scala will get you the latest version, which is 2.11.x. To install Scala 2.10.x with Homebrew, please see this page.

You can also work with Scala via an IntelliJ plugin. (To add a plugin to IntelliJ, go to the tab IntelliJ IDEA/Preferences/IDE Setting/Plugins/ and search for Scala.)

DataVec

DataVec is a general vectorization lib we built for machine-learning tools. It vectorizes raw data into usable vector formats like svmLight, libsvm and ARFF, which our neural nets can work with. ND4J does not require DataVec, but it is useful for loading data into Deeplearning4j neural nets.

Installing DataVec

Take the same steps using Maven to install DataVec that you followed for ND4J. Make sure you have the most recent version of Maven. Please see the examples for the most recent versions.

Installing Deeplearning4j

Deeplearning4j versions should be specified in the same way you did for ND4J, with the version hard-coded in the properties section of the POM, and the version variable cited in each dependency.

The DL4J dependencies you add to the POM will vary with the nature of your project.

In addition to the core dependency, given below, you may also want to install deeplearning4j-cli for the command-line interface, deeplearning4j-scaleout for running parallel on Hadoop or Spark, and others as needed.

<dependency>
 <groupId>org.deeplearning4j</groupId>
 <artifactId>deeplearning4j-core</artifactId>
 <version>${deeplearning4j.version}</version>
</dependency>

More information on installing Deeplearning4j is available on its Getting Started page.

Dev Tools for C on OSX, Windows & Linux

To compile certain ND4J dependencies on Windows or a Linux OS, you will need to install some dev tools for C, including gcc. To check if you have gcc, enter gcc -v on your terminal or command prompt.

OSX

Some versions of the Apple developer tool Xcode will install gcc for you. If you don’t already have gcc, enter brew install gcc into your command prompt.

OpenBlas

To make sure the native libs on the native backend work, you need /opt/OpenBLAS/lib on the system path. After that, enter these commands in the prompt

sudo cp libopenblas.so liblapack.so.3
sudo cp libopenblas.so libblas.so.3

We added this so that Spark would work with OpenBlas.

If OpenBlas is not working correctly, follow these steps:

  • Remove Openblas if you installed it.
  • Run sudo apt-get remove libopenblas-base
  • Download the development version of OpenBLAS
  • git clone git://github.com/xianyi/OpenBLAS
  • cd OpenBLAS
  • make FC=gfortran
  • sudo make PREFIX=/usr/local/ install
  • With Linux, double check if the symlinks for libblas.so.3 and liblapack.so.3 are present anywhere in your LD_LIBRARY_PATH. If they aren’t, add the links to /usr/lib. A symlink is a “symbolic link.” You can set it up like this (the -s makes the link symbolic):
    ln -s TARGET LINK_NAME
    // interpretation: ln -s "to-here" <- "from-here"
    
  • The “from-here” is the symbolic link that does not exist yet, and which you are creating. Here’s StackOverflow on how to create a symlink. And here’s the Linux man page.
  • As a last step, restart your IDE.
  • For complete instructions on how to get native Blas running with Centos 6, see this page.

For OpenBlas on Ubuntu (15.10), please see these instructions. Some additional gymnastics may be necessary to get OpenBlas running:

cd OpenBLAS
make FC=gfortran
sudo make PREFIX=/usr/local/ install

sudo ln -s libopenblas.so libblas.so.3
sudo ln -s libopenblas.so liblapack.so.3

For OpenBlas on Windows, download this file. Extract it to a location such as C:/BLAS. Finally, add that directory to your system’s PATH environment variable.

Windows

Windows users may need to install Visual Studio Community 2013 or later, which is free. You will need to add its path to your PATH environment variable manually. The path will look something like this: C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\bin

Type cl into your CMD. You may get a message informing you that certain .dll files are missing. Make sure that your VS/IDE folder is in the path (see above). If your CMD returns usage info for cl, then it’s in the right place.

If you use Visual Studio:

  • Set up PATH environment variable to point to \bin\ (for cl.exe etc)
  • Also try running vcvars32.bat (also in bin) to set up environment before doing mvn clean install on ND4J (it may save you from copying headers around)
  • vcvars32 may be temporary, so you might need to run it every time you want to do ND4J mvn install.
  • After installing Visual Studio 2015 and setting the PATH variable, you need to run the vcvars32.bat to set up the environment variables (INCLUDE, LIB, LIBPATH) properly so that you don’t have to copy header files. But if you run the bat file from Explorer, since the settings are temporary, they’re not properly set. So run vcvars32.bat from the same CMD window as your mvn install, and all the environment variables will be set correctly.
  • Here is how they should be set:
    INCLUDE = C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\include
    LIB = "C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\lib"
    //so you can link to .lib files^^
    
  • In Visual Studio, you also have to click on C++. It is no longer set by default. (In addition, the include path for Java CPP doesn’t always work on Windows. One workaround is to take the the header files from the include directory of Visual Studio, and put them in the include directory of the Java Run-Time Environment (JRE), where Java is installed. This will affect files such as standardio.h.)
  • For a walkthrough of installing our examples with Git, IntelliJ and Maven, please see our Quickstart page.
  • This page describes how to obtain dll for the Windows 64 platform.

Linux

With Linux, Ubuntu and Centos users will need to follow two separate sets of instructions:

Ubuntu

For Ubuntu, first type:

	sudo apt-get update

Then you’ll need to run a version of this command:

	sudo apt-get install linux-headers-$(uname -r) build-essential

$(uname -r) will vary according to your Linux version. To get your Linux version, open a new window of your terminal and enter this command:

	uname -r

You will see something like this – 3.2.0-23-generic. Whatever you see, copy and paste it into the first line of script in place of $(uname -r). Then insert one space and type build-essential. Watch out for typos. You can press tab to complete any command.

Centos

Enter the following in your terminal (or ssh session) as a root user:

	yum groupinstall 'Development Tools'

After that, you should see a lot of activity and installs on the terminal. To verify that you have, for example, gcc, enter this line:

	gcc --version

For more complete instructions, go here.

GPUs

We support CUDA versions 7.5 and higher.

Once you begin training neural networks on GPUs, you will want to monitor whether and how well the GPUs are working. There are several measures you can take:

Now you’re ready to run the examples. We recommend that you launch your IDE, load the ND4J project and open the examples subdirectory. Locate an example in the file tree on the lefthand side of the IntelliJ window, right click on it, and select the green arrow for “Run” on the drop-down menu.

If everything was installed correctly, you should see numbers appear as the program output at the bottom of the IntelliJ window. Please use these as a sandbox to start experimenting.

Once you’re comfortable with the examples, you might want to change the dependencies defined in the POM files. Learn how to change the dependencies here.