Quick Start Guide

GraalVM is a high-performance runtime for Java and other JVM languages. It contains a compatible JDK and offers distributions based on Java 8 and Java 11. GraalVM comes with multiple compiler optimizations, designed to accelerate Java applications performance while consuming fewer resources. To start using GraalVM, or to migrate from another JDK distribution, you do not have to change any source code. Any application that runs on the Java HotSpot VM will run on GraalVM.

Here you will find information about installing GraalVM, running Java applications with it, and adding support for its accompanying features. Further, you will learn how to build platform-specific native executables of Java-based applications.

If you are new to GraaVM or have little experience using it, we recommend starting with Architectural Overview of GraalVM. There you will find information about GraalVM’s architecture, distributions available, supported platforms, core and additional features, and much more.

Install GraalVM

Getting GraalVM installed and ready-to-go only takes a few minutes.

1. Navigate to GraalVM Downloads. Be sure to download the package appropriate for your operating system and the Java version you need (Java 8 or 11).

2. Unzip the archive to your file system:

on Linux or macOS
```
  tar -xzf <graalvm-archive>.tar.gz
```
on Windows
```
  unzip <graalvm-archive>.zip
```

3. Required for macOS only. Move the downloaded package to its proper location, the /Library/Java/JavaVirtualMachines directory. Since it is a system directory, sudo is required:

  sudo mv <graalvm> /Library/Java/JavaVirtualMachines

To verify if the move is successful, and to get a list of all installed JDKs, run /usr/libexec/java_home -V.

4. Configure the environment variables.

Set the JAVA_HOME environment variable to resolve to the installation directory:

  #Linux
  export JAVA_HOME=<graalvm>

  #macOS
  export JAVA_HOME=/Library/Java/JavaVirtualMachines/<graalvm>/Contents/Home

  #Windows
  setx /M JAVA_HOME "C:\Progra~1\Java\<graalvm>"

Point the PATH environment variable to the GraalVM bin directory:

  #Linux
  export PATH=<graalvm>/bin:$PATH

  #macOS
  export PATH=/Library/Java/JavaVirtualMachines/<graalvm>/Contents/Home/bin:$PATH

  #Windows
  setx /M PATH "C:\Progra~1\Java\<graalvm>\bin;%PATH%"

5. Restart the Command Prompt/Terminal to reload the environment variables. Then use the following command to check whether the variables were set correctly:

on Linux and macOS
```
  echo $PATH
  echo $JAVA_HOME
```
on Windows
```
  echo %PATH%
  echo %JAVA_HOME%
```

6. Optionally, specify GraalVM as the JRE or JDK installation in your Java IDE.

Run Java Applications

GraalVM includes a JDK based on the Java HotSpot VM, and integrates an optimizing just-in-time (JIT) compiler, written in Java. At run time, an application is loaded and executed normally by the JVM.

For demonstration purposes, GraalVM Enterprise based on Java 8 is used.

Check your current Java version:

java version "1.8.0_281"
Java(TM) SE Runtime Environment (build 1.8.0_281-b09)
Java HotSpot(TM) 64-Bit Server VM GraalVM EE 21.0.0 (build 25.281-b09-jvmci-21.0-b05, mixed mode)

The java launcher runs the JVM with the GraalVM default compiler - the GraalVM compiler. Take a look at this typical HelloWorld class:

public class HelloWorld {
  public static void main(String[] args) {
    System.out.println("Hello, World!");
  }
}

Run the following commands to compile this class to bytecode and then execute it:

javac HelloWorld.java
java HelloWorld
Hello World!

Native Image

With GraalVM Native Image technology you can compile Java bytecode into a platform-specific, self-contained, native executable to achieve faster startup and smaller footprint for your application. Native Image is not available by default, but can be easily added using the GraalVM Updater tool:

gu install native-image

The native-image executable will become available in the <graalvm>/bin directory.

Compile the same HelloWorld.java example from above, and then build a native image from Java bytecode:

javac HelloWorld.java
native-image HelloWorld

The last command generates an executable file named helloworld in the current working directory. Invoking it executes the natively compiled code of the HelloWorld class as follows:

./helloworld
Hello, World!

Note: For compilation, Native Image depends on the local toolchain. Ensure you meet the requirements for your platform.

What to Read Next

New Users

Since this Quick Start guide is intended mainly for users new to GraalVM, or users who are familiar with GraalVM but may have little experience using it, consider investigating more complex Java examples.

Oracle Cloud Users

Oracle Cloud users considering GraalVM for their cloud workloads are invited to read GraalVM Enterprise on OCI. This page focuses on using GraalVM Enterprise with the Oracle Cloud Infrastructure Virtual Machine compute instance.

Advanced Users

If you want more in-depth details about the GraalVM compiler, go to its reference page. For more extensive documentation on running Java, proceed to Java Reference. More detailed documentation on the Native Image technology is available here.

If you are looking for the tooling support GraalVM offers, proceed to Debugging and Monitoring Tools.

If you are considering GraalVM as a platform for your future language or tool implementation, go to GraalVM as a Platform.

You can find information on GraalVM security model, and rich API documentation in GraalVM SDK Javadoc.