Using GraalVM and Native Image on Windows 10

Co-authored by Scott Seighman, Oracle

Note: Beginning with GraalVM for JDK 17 / 20, the native-image tool looks for a Visual Studio installation, and (if it finds one) automatically sets your build environment. Therefore, you can run native-imagein a Command Prompt or a PowerShell without any additional installation. For more details, see the guide.

This post will help anyone using the Windows operating system install the high-performance GraalVM JDK and its Native Image feature.

We’ve seen an increasing number of Windows 10 users express interest in using GraalVM Native Image, which is an ahead-of-time (AOT) compilation technology that packages Java bytecode to a standalone executable. This executable is a native application like any other on the user’s system, and typically achieves a much faster startup time while occupying a smaller footprint.

There are two GraalVM editions to choose from: Community and Enterprise. These guidelines should work equally for both. Community is open source (which implies free and no strings) and Enterprise “offers better performance, scalability, and security” along with 24/7 support from Oracle.

GraalVM installation on Windows is quick and easy, then there are just a few prerequisites for using Native Image. Let’s go step by step.

Part 1: Install GraalVM and Native Image

1. Download GraalVM. To find the GraalVM Enterprise version, navigate to the Oracle GraalVM Downloads page. To download GraalVM Community edition, go to the GraalVM Releases repository on GitHub. Select a Java version (8, 11, or 16) and download.
2. Change the directory to the location where you want to install GraalVM, and then move the downloaded .zip archive to it.
3. Unzip the archive.
4. Next you should configure the runtime environment, being mindful that there may be multiple JDKs installed on the machine. Open a Windows command prompt and run the following commands.
   - Point the PATH environment variable to the GraalVM bin directory: setx /M PATH “C:\Progra~1\Java\<graalvm install dir>\bin;%PATH%”
   - Set the JAVA_HOME environment variable to resolve to the GraalVM installation directory:
   setx /M JAVA_HOME “C:\Progra~1\Java\<graalvm install dir>”

5. To verify if GraalVM is installed successfully, restart the command prompt and execute java -version.

To add Native Image support in GraalVM, you need to install it. GraalVM comes with a package manager, gu, that downloads and installs packages not included in the core distribution.

1. To install Native Image, run:

gu install native-image

If you are a GraalVM Enterprise user, you will be prompted to accept a license. Follow the onscreen messages.

2. Check for installed features to see if Native Image was added:

C:\> gu list
ComponentId             Version             Component name      Origin
--------------------------------- --------------------------------
js                       21.0.0     Graal.js           -
graalvm                  21.0.0     GraalVM Core       -
native-image             21.0.0     Native Image       Early adopter

On Windows, Native Image requires Visual Studio Code and Microsoft Visual C++(MSVC). There are two installation options:

• Install the Visual Studio Code Build Tools with the Windows 10 SDK
• Install Visual Studio Code with the Windows 10 SDK

Part 2: Install Visual Studio Build Tools and Windows 10 SDK

You can use Visual Studio 2017 version 15.9 or later. We tested on Visual Studio 2019.

VISUAL STUDIO:

1. Download the Visual Studio Build Tools (C development environment) from visualstudio.microsoft.com.
2. Start the Visual Studio Build Tools installation by clicking on the .exe file, and then press Continue:

3. Check the Desktop development with C++ box in the main window. Also, on the right side under Installation Details, choose Windows 10 SDK, and click the Install button.

4. After the installation completes, reboot your system.

WINDOWS 10 SDK:

Next, if you have Visual Studio 2019 installed, you will need to ensure Windows 10 SDK is available too:

1. Open the Visual Studio Installer:

2. Under the Installed tab, click Modify and choose Individual Components:

3. Then scroll to the bottom and check if Windows 10 SDK is installed and confirm the build tools are installed:

Now that you have the Windows 10 SDK and Visual Studio tooling installed, you can start using GraalVM Native Image.

Part 3. Start Using Native Image on Windows

On Windows, the native-image builder will only work when it’s executed from the x64 Native Tools Command Prompt. The command for initiating an x64 Native Tools command prompt is different if you only have the Visual Studio Build Tools installed, versus if you have the full VS Code 2019 installed.

Use this command if you have the Visual Studio Build Tools installed:

C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvars64.bat

And use this command if you installed the full VS Code 2019:

C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\Tools\vcvars64.bat

Alternatively, you can launch a Dev command prompt from the Visual Studio 2019 interface:

Now let’s experiment with Native Image and see what it can do!

1. Save this simple code to a HelloWorld.java file:

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

2. Compile and run it on the JVM:

C:\> javac HelloWorld
C:\> java HelloWorld

3. Now compile the class into a native executable:

C:\> native-image HelloWorld

This will produce an executable file, helloworld, in the working directory.

4. Now execute it:

C:\> helloworld    
Hello, GraalVM Native Image!

Compare the startup times when running on the JVM (step 2) versus when executing a binary produced by native-image (step 4). Or measure the time in PowerShell:

C:\> Measure-Command {".\helloworld"}
    
Days              : 0
Hours             : 0
Minutes           : 0
Seconds           : 0
Milliseconds      : 3
Ticks             : 38000
TotalDays         : 4.39814814814815E-08
TotalHours        : 1.05555555555556E-06
TotalMinutes      : 6.33333333333333E-05
TotalSeconds      : 0.0038
TotalMilliseconds : 3.8

Summary
Installing GraalVM and its features on Windows is easy! Just remember, there are certain requirements in order to use Native Image. With Native Image, you can take full advantage of vastly increased startup time and smaller footprint for compiling your Java applications ahead-of-time on Windows platforms. This guide was written for Windows 10, but should be valid for Windows 7 and 8 as well.