Visit Azul.com Support

Migrating to Azul Zulu from Another OpenJDK Distribution

Table of Contents
Need help?
Schedule a consultation with an Azul performance expert.
Contact Us

Azul Zulu Builds of OpenJDK (Azul Zulu) are built from the same OpenJDK sources as every other OpenJDK distribution and are Java SE compliant and TCK verified. Moving to Azul Zulu is therefore a replacement of the runtime, not a port of your application: the same Java version behaves the same way, and your code, build files, and dependencies do not change.

This guide describes how to identify the distribution you run today, how to replace it with the matching Azul Zulu package, and how to confirm afterwards that your application really runs on Azul Zulu.

Tip
 You do not have to remove your current JDK to try Azul Zulu. Several JDKs can be installed next to each other, as described in Uninstalling other OpenJDK distributions.

Before You Start

Collect the following information about your current setup. You need it to pick the matching Azul Zulu package, and to fall back if you have to.

  1. The Java version and the vendor of the JDK you run today:

     
    java -version

  2. Whether you use a JDK or only a JRE, and whether you need JavaFX.

  3. The value of JAVA_HOME and the entries in PATH that point at the current JDK.

  4. The installation path and, on Linux, the name of the installed package.

  5. Any JVM flags your application starts with, so that you can check them against Supported Platforms and the release notes.

Then confirm two things:

  • That your combination of operating system, CPU architecture, and Java version is listed in Supported Platforms.

  • Which distribution of Azul Zulu you need. Azul Zulu CA is the free distribution, Azul Zulu SA is the supported distribution available to Azul Core customers. The installation steps differ, so pick the right guide in the sections below.

Identify Your Current JDK: Temurin, Corretto, Oracle JDK, and Others

The second line of the java -version output names the distribution. Use the following table to recognize it and to find the packages you replace.

Distribution Typical java -version vendor string Typical Linux package names

Eclipse Temurin (Eclipse Adoptium, formerly AdoptOpenJDK)

OpenJDK Runtime Environment Temurin-…​

temurin-<X>-jdk, adoptopenjdk-<X>-hotspot

Amazon Corretto

OpenJDK Runtime Environment Corretto-…​

java-<X>-amazon-corretto-jdk, java-<X>-amazon-corretto-devel

Oracle JDK / Oracle Java SE

Java™ SE Runtime Environment

jdk-<X>, jre1.8.0_<X>

Oracle OpenJDK

OpenJDK Runtime Environment (build …​) without a vendor name

jdk-<X>

Microsoft Build of OpenJDK

OpenJDK Runtime Environment Microsoft-…​

msopenjdk-<X>

BellSoft Liberica JDK

OpenJDK Runtime Environment (build …​) with Liberica in the VM line

bellsoft-java<X>

SapMachine

OpenJDK Runtime Environment SapMachine-…​

sapmachine-<X>-jdk

Red Hat build of OpenJDK

OpenJDK Runtime Environment (Red Hat-…​)

java-<X>-openjdk, java-<X>-openjdk-devel

Azul Zulu (already migrated)

OpenJDK Runtime Environment Zulu…​-CA or …​-SA

zulu<X>-ca-jdk, zulu<X>-jdk
Note
 A distribution that reports no vendor name at all is usually a build made from OpenJDK sources by the operating system vendor. Check the package name and the installation path to be sure.

Choose the Matching Azul Zulu Package

Every distribution builds a specific OpenJDK version, so a migration keeps the Java version you run today. What differs is the version number a distribution reports for itself, and every vendor numbers its builds in its own way. Eclipse Temurin appends the OpenJDK build number, as in 21.0.5+11. Amazon Corretto adds its own build and revision numbers, as in 21.0.5.11.1. Azul Zulu has a version number of its own, and Azul Zulu 21.38.21 is the build that contains OpenJDK 21.0.5.

So compare the OpenJDK version rather than the version a distribution reports for itself. The Version Search Tool translates between the two: it looks up the Azul Zulu version that contains the OpenJDK version you run today.

Replace your current package with the Azul Zulu package in the same format:

You install today with Free distribution (Zulu CA) Supported distribution (Zulu SA)

apt on Debian, Ubuntu, and derivatives

Install Zulu CA DEB packages

Install Zulu SA DEB packages

yum, dnf, or zypper on Red Hat, Fedora, and SUSE

Install Zulu CA RPM packages

Install Zulu SA RPM packages

apk on Alpine Linux

Install Zulu CA APK packages

Install Zulu SA APK packages

An archive you unpack yourself

Install Zulu CA from TAR.GZ

Download with the Azul Metadata API

An installer on Windows

Install Zulu on Windows

An installer on macOS

Install Zulu on macOS

A container base image

Run Zulu CA in Docker

Run Zulu SA in Docker

SDKMAN!

Install Zulu with SDKMAN!

If your current distribution does not bundle JavaFX and your application needs it, choose an Azul Zulu package that includes JavaFX instead of adding a separate JavaFX distribution. See Supported Platforms for the versions in which JavaFX is available.

Migrate from Eclipse Temurin, Eclipse Adoptium, or AdoptOpenJDK

Eclipse Temurin is the current name of the distribution that was called AdoptOpenJDK before it moved to the Eclipse Foundation as Eclipse Adoptium. Both names still appear in older installations and scripts.

  1. Note the Java version reported by java -version, and install the same Azul Zulu version with the guide for your package format in Choose the Matching Azul Zulu Package.

  2. Update JAVA_HOME and PATH to the Azul Zulu installation folder. On Linux, the packages from the Azul repositories install into /usr/lib/jvm/zulu<X>-ca-<arch>.

  3. On Linux, if your system selects the default JDK through update-alternatives or alternatives, point the java and javac alternatives at the Azul Zulu installation.

  4. Update any container image, CI configuration, or build script that refers to a Temurin image or a Temurin installation path.

  5. Remove the Temurin packages once your application runs correctly, as described in Uninstalling other OpenJDK distributions.

What changes and what does not:

  • The vendor strings reported by java -version and by the java.vendor and java.vm.vendor system properties change. Code or tooling that tests these values needs to be updated.

  • The installation path changes, so anything that hard-codes a Temurin path needs to be updated.

  • The Java API, the bytecode, and the standard JVM options do not change.

Migrate from Amazon Corretto

Amazon Corretto is also referred to as AWS Corretto. The migration follows the same steps as for Temurin.

  1. Install the matching Azul Zulu version with the guide for your package format in Choose the Matching Azul Zulu Package.

  2. Replace the Corretto packages, typically named java-<X>-amazon-corretto-jdk or java-<X>-amazon-corretto-devel, and update JAVA_HOME and PATH.

  3. On Amazon Linux, the Azul RPM repository is used in the same way as on other Red Hat derivatives. See Install Zulu CA RPM packages.

  4. Update container images that use a Corretto base image, and CI jobs that select Corretto through a setup action or a toolchain declaration.

  5. Verify the result as described in Verify the Migration.

Migrate from Oracle JDK or Oracle Java SE

Migrating away from Oracle Java has a few extra considerations, because the Oracle JDK contains some components that are not part of OpenJDK, and because the Windows installer shares registry keys with Azul Zulu.

Read these two pages before you start:

The steps are:

  1. Record the exact Oracle package you replace: JRE or JDK, the version, and the installation path.

  2. On Windows, uninstall Oracle Java first, then install Azul Zulu with the guide in Install Zulu on Windows.

  3. On Linux and macOS, install the matching Azul Zulu version and update JAVA_HOME and PATH.

  4. Check whether your application uses components that the Oracle JDK provided and OpenJDK does not. If it does, request access to the CCK through About Azul Commercial Compatibility Kit.

  5. If your application runs Java Web Start applications, replace Java Web Start with IcedTea-Web.

  6. Review the JVM flags your application starts with. Flags that exist only in the Oracle JDK have to be removed or replaced.

  7. Verify the result as described in Verify the Migration.

Note
 Oracle JDK 8 bundled JavaFX. If you migrate from Oracle JDK 8 and your application uses JavaFX, choose an Azul Zulu package that includes JavaFX.

Verify the Migration

  1. Confirm that the JDK on the PATH is Azul Zulu:

     
    java -version

    The second line of the output names Zulu, for example:

     
    OpenJDK Runtime Environment Zulu<version>-CA (build <version>)

  2. Confirm that JAVA_HOME points at the Azul Zulu installation folder, and that no other JDK appears earlier on the PATH.

  3. Confirm that your build tool uses the same JDK. Maven and Gradle can be configured with a toolchain that still selects the previous distribution.

  4. Run your test suite, and check the application logs for warnings about unrecognized JVM options.

  5. Compare startup time, memory use, and garbage collection behavior with the values you measured before the migration.

Run Azul Zulu Next to Your Current JDK

You do not have to remove the previous distribution. Installing several JDKs next to each other is a low-risk way to test the migration first:

Azul Zulu or Azul Zing?

Azul provides two Java runtimes, and a migration is a good moment to choose between them. The Azul Core documentation home page compares them in more detail.

  • Azul Zulu Builds of OpenJDK is a build of OpenJDK and a one-to-one replacement for any other OpenJDK distribution. It is the subject of this guide and part of Azul Core.

  • Azul Zing Builds of OpenJDK is a JVM based on OpenJDK and optimized for low latency and high throughput, with the C4 garbage collector and the Falcon compiler. It is part of Azul Prime.

Both run the same Java bytecode, so an application that runs on another OpenJDK distribution runs on either of them without code changes. Choose Azul Zing when garbage collection pauses or warm-up time limit your application, and Azul Zulu for general-purpose workloads.

For the migration steps and the tuning options of Azul Prime, see the Azul Prime documentation.

Frequently Asked Questions

  1. Is Azul Zulu a drop-in replacement for Oracle JDK?

    Yes. Azul Zulu is built from OpenJDK sources and is Java SE compliant and TCK verified, so your application runs without code changes. Components that exist only in the closed-source Oracle JDK are covered by the Azul Commercial Compatibility Kit.

  2. How do I switch from Eclipse Temurin to Azul Zulu?

    Install the Azul Zulu package with the same Java version and package format, update JAVA_HOME and PATH, and remove the Temurin packages. See Migrate from Eclipse Temurin, Eclipse Adoptium, or AdoptOpenJDK.

  3. I still use AdoptOpenJDK. Does this guide apply?

    Yes. AdoptOpenJDK was renamed to Eclipse Adoptium, and its builds are now called Eclipse Temurin. The migration steps are the same.

  4. How do I switch from Amazon Corretto to Azul Zulu?

    Replace the java-<X>-amazon-corretto packages with the Azul Zulu packages for the same Java version. See Migrate from Amazon Corretto.

  5. Do I have to change my Java version when I migrate?

    No. Azul Zulu is available for the same OpenJDK versions as the other distributions. Migrate first, and upgrade the Java version as a separate step.

  6. Can I keep my current JDK installed?

    Yes. Several JDKs can be installed on the same machine. See Run Azul Zulu Next to Your Current JDK.

  7. Does the vendor string change after the migration?

    Yes. The java.vendor and java.vm.vendor system properties, and the java -version output, report Azul. Update any code or tooling that checks these values.