TensorFlow for Java

Java bindings for TensorFlow. (Javadoc)

WARNING: The TensorFlow Java API is not currently covered by the TensorFlow API stability guarantees.
For using TensorFlow on Android refer to contrib/android, makefile and/or the Android demo.

Quickstart: Using Apache Maven

TensorFlow for Java releases are included in Maven Central and support Linux, OS X and Windows. To use it, add the following dependency to your project's pom.xml:

<dependency>
  <groupId>org.tensorflow</groupId>
  <artifactId>tensorflow</artifactId>
  <version>1.1.0-rc2</version>
</dependency>

That's all. As an example, to create a Maven project for the label image example:

Create a pom.xml:

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.myorg</groupId>
    <artifactId>label-image</artifactId>
    <version>1.0-SNAPSHOT</version>
    <properties>
      <exec.mainClass>org.tensorflow.examples.LabelImage</exec.mainClass>
      <!-- The LabelImage example code requires at least JDK 1.7. -->
      <!-- The maven compiler plugin defaults to a lower version -->
      <maven.compiler.source>1.7</maven.compiler.source>
      <maven.compiler.target>1.7</maven.compiler.target>
    </properties>
    <dependencies>
      <dependency>
        <groupId>org.tensorflow</groupId>
        <artifactId>tensorflow</artifactId>
        <version>1.1.0-rc2</version>
      </dependency>
    </dependencies>
</project>

Download the example source into src/main/java/org/tensorflow/examples. On Linux and OS X, the following script should work:

mkdir -p src/main/java/org/tensorflow/examples
curl -L "https://raw.githubusercontent.com/tensorflow/tensorflow/master/tensorflow/java/src/main/java/org/tensorflow/examples/LabelImage.java" -o src/main/java/org/tensorflow/examples/LabelImage.java

Compile and execute:
```
mvn compile exec:java
```

Quickstart: Using `java` and `javac`

This section describes how to use TensorFlow armed with just a JDK installation.

Download the Java archive (JAR): libtensorflow.jar (optionally, the Java sources: libtensorflow-src.jar).
Download the native library. GPU-enabled versions required CUDA 8 and cuDNN 5.1. For other versions, the native library will need to be built from source (see below).
- Linux: CPU-only, GPU-enabled
- OS X: CPU-only, GPU-enabled
- Windows: CPU-only
The following shell snippet downloads and extracts the native library on Linux and OS X. For Windows, download and extract manually.
```
TF_TYPE="cpu" # Set to "gpu" to enable GPU support
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
mkdir -p ./jni
curl -L \
  "https://storage.googleapis.com/tensorflow/libtensorflow/libtensorflow_jni-${TF_TYPE}-${OS}-x86_64-1.1.0-rc2.tar.gz" |
tar -xz -C ./jni
```

Include the downloaded .jar in the classpath during compilation. For example, if your program looks like the following:

import org.tensorflow.TensorFlow;

public class MyClass {
  public static void main(String[] args) {
    System.out.println("I'm using TensorFlow version: " +  TensorFlow.version());
  }
}

then it should be compiled with:

javac -cp libtensorflow-1.1.0-rc2.jar MyClass.java

For a more sophisticated example, see LabelImage.java, which can be compiled with:

javac \
  -cp libtensorflow-1.1.0-rc2.jar \
  ./src/main/java/org/tensorflow/examples/LabelImage.java

Include the downloaded .jar in the classpath and the native library in the library path during execution. For example:

java -cp libtensorflow-1.1.0-rc2.jar:. -Djava.library.path=./jni MyClass

or for the LabelImage example:

java \
  -Djava.library.path=./jni \
  -cp libtensorflow-1.1.0-rc2.jar:./src/main/java \
  org.tensorflow.examples.LabelImage

Building from source

If the quickstart instructions above do not work out, the TensorFlow Java and native libraries will need to be built from source.

Install bazel
Setup the environment to buile TensorFlow from source code (Linux or Mac OS X). If you'd like to skip reading those details and do not care about GPU support, try the following:
```
# On Linux
sudo apt-get install python swig python-numpy

# On Mac OS X with homebrew
brew install swig
```

Configure (e.g., enable GPU support) and build:

./configure
bazel build --config opt \
  //tensorflow/java:tensorflow \
  //tensorflow/java:libtensorflow_jni

The JAR (libtensorflow.jar) and native library (libtensorflow_jni.so on Linux, libtensorflow_jni.dylib on OS X, tensorflow_jni.dll on Windows) will be in bazel-bin/tensorflow/java. Using these artifacts follow both steps 3 and 4 in the previous section in order to get your application up and running.

Installation on Windows requires the more experimental bazel on Windows. Details are elided here, but find inspiration in the script used for building the release archive: tensorflow/tools/ci_build/windows/libtensorflow_cpu.sh.

Maven

Details of the release process for Maven Central are in maven/README.md. However, for development, you can push the library built from source to a local Maven repository with:

bazel build -c opt //tensorflow/java:pom
mvn install:install-file \
  -Dfile=../../bazel-bin/tensorflow/java/libtensorflow.jar \
  -DpomFile=../../bazel-bin/tensorflow/java/pom.xml

And then rever to this library in a project's pom.xml with: (replacing 1.0.head with the appropriate version):

<dependency>
  <groupId>org.tensorflow</groupId>
  <artifactId>libtensorflow</artifactId>
  <version>1.0.head</version>
</dependency>

Bazel

If your project uses bazel for builds, add a dependency on //tensorflow/java:tensorflow to the java_binary or java_library rule. For example:

bazel run -c opt //tensorflow/java/src/main/java/org/tensorflow/examples:label_image