Install TornadoVM: SDKMAN!, Build from Source, Maven

TornadoVM ships as a prebuilt SDK that you can install in under two minutes with SDKMAN!, as a source build for contributors who need to modify the runtime or backends, and as a Maven Central artifact for teams that want GPU acceleration inside an existing Java project without installing the full SDK. Choose the path that fits your workflow — all three routes land at the same API.

Prerequisites

Before installing, make sure the following are in place on your system.

JDK 21 or JDK 25

JAVA_HOME must point to a JDK 21 (or JDK 25) installation. GraalVM based on JDK 21 also works. Run java -version to confirm.

GCC / G++ ≥ 13

The native driver libraries are compiled at install time. GCC/G++ version 13 or later is required on Linux. On macOS, Xcode Command Line Tools satisfy this requirement.

GPU Drivers

Install the vendor driver that matches your target backend: the OpenCL runtime (AMD/Intel), the NVIDIA CUDA Toolkit, or macOS (Metal is built in). Without a driver, TornadoVM falls back to a CPU OpenCL device.

CUDA Toolkit (NVIDIA only)

For the CUDA backend and NVIDIA library tasks (cuBLAS, cuFFT, cuDNN), install the CUDA Toolkit and ensure /usr/local/cuda or $CUDA_PATH is set. NVRTC must be present.

The system you build TornadoVM on determines which systems the resulting SDK can run on. An SDK built on Ubuntu 24.04 with GCC 13 requires GLIBCXX_3.4.32+ on the target machine. If you plan to distribute the SDK, build on the oldest OS version you intend to support, or use the SDKMAN! prebuilt route instead.

Method 1: SDKMAN! (Recommended)

SDKMAN! is the fastest way to install TornadoVM. It handles the JDK, sets TORNADOVM_HOME, and configures your shell automatically.

Install SDKMAN! (if not already installed)

curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"

Choose a backend variant and install

The default install picks the latest release with the OpenCL backend. Use a versioned variant to select a specific backend:

sdk install tornadovm

Variant	Targets	Notes
`5.2.0-opencl`	NVIDIA, AMD, Intel GPUs; multi-core CPUs	Default — broadest hardware support
`5.2.0-cuda`	NVIDIA GPUs (PTX, Tensor Cores, cuBLAS/cuFFT/cuDNN)	Requires CUDA Toolkit + NVRTC
`5.2.0-metal`	Apple Silicon M1–M4	macOS only; no extra install needed
`5.2.0-full`	All of the above	Largest download; covers every backend

Verify the installation

tornado --devices

You should see at least one device listed. If you see Number of Tornado drivers: 0, check that the correct GPU driver is installed for your chosen backend.

Run sdk list tornadovm to see every available version/backend combination, including JDK 25 builds.

Method 2: Build From Source

Building from source is recommended for contributors, users who need the latest develop branch, or anyone who wants a custom backend combination. The installer script handles downloading a JDK, building all Maven modules, and compiling the native driver libraries.

Linux / macOS
Windows

Clone the repository

git clone https://github.com/beehive-lab/TornadoVM.git
cd TornadoVM

Run the installer script

The tornadovm-installer script accepts a --jdk keyword and one or more --backend values. Run --listJDKs to see all supported JDK keywords.

./bin/tornadovm-installer --jdk jdk21 --backend opencl

Source the environment

After the build completes, the installer prints a source command. Run it (or add it to your shell profile):

source setvars.sh

Verify

tornado --devices

On macOS, set MACOSX_DEPLOYMENT_TARGET before building if you need the SDK to run on older macOS versions:

export MACOSX_DEPLOYMENT_TARGET=11.0
./bin/tornadovm-installer --jdk jdk21 --backend metal

Clone the repository

git clone https://github.com/beehive-lab/TornadoVM.git
cd TornadoVM

Create and activate a Python virtual environment

The installer is a Python script. Windows requires a venv and the Visual Studio environment:

python -m venv .venv
.venv\Scripts\activate.bat
.\bin\windowsMicrosoftStudioTools2022.cmd

Run the installer

python bin\tornadovm-installer --jdk jdk21 --backend opencl

Verify

tornado --devices

Windows SDKs built with Visual Studio 2015–2022 require the Visual C++ Redistributable (VCRUNTIME140.dll, MSVCP140.dll) on target machines. Download it from aka.ms/vs/17/release/vc_redist.x64.exe.

Available Installer Flags

Flag	Description
`--jdk <keyword>`	JDK to download and use (e.g., `jdk21`, `graal-jdk-21`). Run `--listJDKs` to list all.
`--backend <name>`	Backend(s) to build: `opencl`, `cuda`, `metal`, or comma-separated combinations.
`--auto-deps`	Automatically download any missing build dependencies.
`--mvn_single_threaded`	Run Maven in single-threaded mode (useful on low-RAM machines).
`--polyglot`	Enable Truffle interoperability with GraalVM.
`--listJDKs`	Print all supported JDK keywords and exit.

Build the CUDA backend on its own — do not combine it with OpenCL in the same build if you intend to run the unit-test suite. With both backends active, tests may silently run on the OpenCL device and report false positives.

Method 3: Maven Dependency

If you only want to write TornadoVM-accelerated code (not run the SDK launcher), add the API and runtime artifacts to your pom.xml. The artifact version suffix must match the JDK you run on.

<dependencies>
  <dependency>
    <groupId>io.github.beehive-lab</groupId>
    <artifactId>tornado-api</artifactId>
    <version>5.2.0-jdk21</version>
  </dependency>
  <dependency>
    <groupId>io.github.beehive-lab</groupId>
    <artifactId>tornado-runtime</artifactId>
    <version>5.2.0-jdk21</version>
  </dependency>
</dependencies>

Adding the Maven dependency gives you the API and runtime JARs but does not install the native driver libraries. You still need a TornadoVM SDK installation (SDKMAN! or source build) on the machine where the application executes, so the JVM can load the native backends at runtime.

Verifying the Installation

Run the following command to list every GPU and CPU device that TornadoVM has discovered:

tornado --devices

Each device is identified by a <driverNumber>:<deviceNumber> pair. Example output on a machine with an NVIDIA GPU and an Intel integrated GPU:

Number of Tornado drivers: 2
Total number of CUDA devices  : 1
Tornado device=0:0
  CUDA -- GeForce GTX 1650
    Global Memory Size: 3.8 GB
    Local Memory Size: 48.0 KB
    Max WorkGroup Configuration: [1024, 1024, 64]

Total number of OpenCL devices  : 2
Tornado device=1:0
  NVIDIA CUDA -- GeForce GTX 1650
    Global Memory Size: 3.8 GB
Tornado device=1:1
  Intel(R) OpenCL HD Graphics -- Intel(R) Gen9 HD Graphics NEO
    Global Memory Size: 24.8 GB
    Device OpenCL C version: OpenCL C 2.0

You should see at least one device. If the list is empty or you see only CPU devices when you expect a GPU, verify that the correct GPU driver is installed and that you chose the matching backend variant at install time.

To run on a specific device, pass a JVM property using the <taskGraphName>.<taskName>.device format:

# Run on device 1:1 (Intel HD Graphics in the example above)
tornado --jvm="-Ds0.t0.device=1:1" -cp myapp.jar com.example.Main

Backend-Specific Notes

CUDA Backend

Requires the NVIDIA CUDA Toolkit (including NVRTC). Install from developer.nvidia.com/cuda-downloads.
Ensure /usr/local/cuda exists or $CUDA_PATH is set before building or running.
For cuBLAS, cuFFT, and cuDNN library tasks, the corresponding CUDA libraries must be installed (they are included in most CUDA Toolkit bundles).
Build the CUDA backend in isolation when running unit tests to avoid false positives from mixed-backend test execution.

OpenCL Backend

On NVIDIA, the OpenCL runtime is bundled with the CUDA Toolkit; no extra install needed.
On AMD, install the ROCm OpenCL runtime or the AMDGPU-PRO driver stack.
On Intel, install the Intel oneAPI Base Toolkit or the Intel OpenCL runtime.
On Linux CPU, the POCL (Portable Computing Language) runtime provides a software OpenCL device if no GPU driver is present.

Metal Backend (macOS)

Metal is built into macOS — no additional driver install is required.
Supported on Apple Silicon M1, M2, M3, and M4 chips.
Requires macOS 11 (Big Sur) or later.
When building from source, set MACOSX_DEPLOYMENT_TARGET=11.0 if the SDK needs to run on macOS 11 targets.
The Metal backend was introduced in TornadoVM 5.2.0.

Get Started

Programming Guide

Backends

NVIDIA Integration

Guides

Contributing

Install TornadoVM: SDKMAN!, Build from Source, Maven

Prerequisites

JDK 21 or JDK 25

GCC / G++ ≥ 13

GPU Drivers

CUDA Toolkit (NVIDIA only)

Method 1: SDKMAN! (Recommended)

Method 2: Build From Source

Available Installer Flags

Method 3: Maven Dependency

Verifying the Installation

Backend-Specific Notes

Build docs developers (and LLMs) love

Get Started

Programming Guide

Backends

NVIDIA Integration

Guides

Contributing

Documentation Index

​Prerequisites

JDK 21 or JDK 25

GCC / G++ ≥ 13

GPU Drivers

CUDA Toolkit (NVIDIA only)

​Method 1: SDKMAN! (Recommended)

​Method 2: Build From Source

​Available Installer Flags

​Method 3: Maven Dependency

​Verifying the Installation

​Backend-Specific Notes

Build docs developers (and LLMs) love

Prerequisites

Method 1: SDKMAN! (Recommended)

Method 2: Build From Source

Available Installer Flags

Method 3: Maven Dependency

Verifying the Installation

Backend-Specific Notes