Oracle JDK to OpenJDK: a practical migration checklist

For most server workloads, moving from Oracle JDK to an OpenJDK distribution of the same version is one of the lowest-risk changes you can make to a Java runtime. Oracle JDK and the major OpenJDK builds come from the same source code, and the reputable distributions are tested against the Java SE Technology Compatibility Kit (TCK).

"Low risk" isn't "no risk," though. The failures we see in vendor swaps are rarely about Java language behavior. They come from what surrounds the runtime: trust stores, install paths, startup flags, bundled components and applications that look for Oracle specifically.

This checklist is what we work through on every migration.

Step 0: Know what you're migrating

You can't migrate what you haven't found. Before you pick a distribution, you need a list of every Oracle JDK and JRE with:

• host, container image or artifact where it lives
• version and exact build
• whether it's standalone, used by an app server, or bundled inside a vendor product
• the application and owner that depend on it
• how it gets there (golden image, config management, manual install, vendor installer)

That last field matters more than people expect. If you migrate a server but the golden image still installs Oracle JDK, it comes back on the next rebuild. See finding every JVM in your estate.

Step 1: Choose a distribution

Several vendors publish free, production-ready OpenJDK builds. Most also offer paid support. The main ones:

The criteria that actually matter:

• LTS support length. How long will this vendor ship security updates for the versions you run? Check the vendor's published roadmap for each version you need, especially Java 8 and 11.
• Update cadence. Updates should follow the quarterly Critical Patch Update schedule (January, April, July, October), released promptly after each one.
• Commercial support. Do you need a contract and an SLA for production incidents? Some distributions sell support directly; for others it's available from third parties.
• Platform coverage. Operating systems, CPU architectures (x86-64, ARM64), container base images, and installers for Windows if you have Windows servers or desktops.
• TCK certification. Confirm the builds you'll use are TCK-tested for the versions you need.
• Standardization. One distribution across the estate is usually easier to patch, scan and support than several. Pick one default and allow exceptions only with a reason.

Step 2: Check the known differences

These are the areas where vendor swaps actually cause problems.

Removed or unbundled components (mostly Java 8)

• JavaFX. Oracle JDK 8 bundled JavaFX. Most OpenJDK 8 builds don't. Applications with JavaFX user interfaces need a build that includes it (some vendors offer these) or a separate OpenJFX dependency.
• Java Web Start and the browser plugin. These were part of Oracle JDK 8 but were never in OpenJDK, and were removed from Oracle JDK in 11. Applications launched via JNLP need an alternative launcher such as OpenWebStart, or a different delivery method.

Startup flags

• -XX:+UnlockCommercialFeatures. Older Oracle JDK 8 builds needed this flag to enable Java Flight Recorder, which was a commercial feature at the time. Startup scripts that still pass it may fail with an unrecognized-option error on other runtimes, which means the JVM doesn't start. Search every start script, service unit, container entrypoint and app-server config for commercial and Oracle-specific flags.
• Deprecated or obsolete flags in general. If the migration also changes the build level, check the startup options against the target version's documentation.

Trust stores

• cacerts contents differ between vendors. Each distribution curates its own default set of trusted root CAs. If an application connects to a partner or internal service whose certificate chains to a root that's in Oracle's store but not your new vendor's, TLS handshakes will fail.
• Custom certificates added by hand to the old JDK's cacerts will not be carried over. Inventory them and re-import them, or better, move to a managed trust store outside the JDK directory.

Paths, installers and registry keys

• JAVA_HOME and hard-coded paths. Scripts and service definitions often point at paths like an Oracle-specific install directory. Find them before you uninstall anything.
• Windows registry keys. Some applications find Java through Oracle's registry entries instead of JAVA_HOME. Check whether your chosen distribution's installer can set compatible keys, and test the applications that depend on them.
• Alternatives and symlinks on Linux. Make sure java on the PATH resolves to the runtime you think it does.

Rendering and fonts

• Older Oracle JDK 8 builds used a different font rasterizer from OpenJDK builds, so reports, PDF generation and desktop UIs can render text slightly differently. This rarely matters for services, but it can for document-generation workloads.

Vendor certification

• Third-party products that certify only Oracle JDK. Some commercial applications list only Oracle JDK in their support matrix. Running them on another build may be technically fine and still unsupported. Ask the vendor, get the answer in writing, and record it. See patching JVMs inside vendor products.

Step 3: Verify, then roll out progressively

For a same-version vendor swap on a non-critical application, you usually don't need a full regression cycle. You do need:

1. Smoke tests covering startup, the main user paths, outbound TLS connections and scheduled jobs.
2. A canary. Move one instance or a small share of traffic first, and compare error rates, latency, GC behavior and log noise with the old runtime.
3. A tested rollback. Keep the previous runtime available until the new one has been stable for an agreed period, and know exactly how to switch back.

For business-critical systems, add shadow-traffic comparison or targeted regression tests on the paths most exposed to runtime differences. We describe the thinking in fast detection and rollback instead of regression testing and the common failure patterns in how JVM patches break production.

Step 4: Remove Oracle, don't just re-point

This is where many migrations stop short. Changing JAVA_HOME to the new runtime leaves the Oracle binaries on disk, and from a licensing point of view an installed Oracle JDK is still an Oracle JDK.

• Uninstall Oracle JDK and JRE packages, and delete leftover directories.
• Update the sources: golden images, container base images, configuration-management roles, internal package mirrors and software catalogs.
• Block reintroduction. Add a check in image builds or CI that fails if an Oracle JDK appears.
• Re-scan after cleanup to confirm nothing remains.

Step 5: Keep the evidence

Record what was migrated or removed, where, when and by whom, with before-and-after scan output. If a licensing review happens later, dated evidence of removal is far more persuasive than a statement that "we moved off Oracle last year." This matters especially given how Oracle's employee-based metric works.

The checklist

1. Build a complete inventory of Oracle JDK and JRE installs, including bundled and containerized ones.
2. Record the owner, the dependent applications and how each install gets provisioned.
3. Choose a default OpenJDK distribution and document the exceptions policy.
4. Flag JavaFX, Java Web Start and other Oracle-8-only dependencies.
5. Search startup configuration for -XX:+UnlockCommercialFeatures and other Oracle-specific or obsolete flags.
6. Compare trust stores and re-import custom certificates.
7. Find hard-coded paths, JAVA_HOME settings and registry dependencies.
8. Confirm vendor support for third-party products, in writing.
9. Smoke test, canary and keep a rehearsed rollback.
10. Uninstall Oracle binaries and fix the golden images and automation that installed them.
11. Re-scan to confirm removal.
12. Archive the evidence.

What to do next

If you want this done on a fixed timeline, our OpenJDK migration service runs the whole checklist, starting from a JVM discovery and estate assessment so nothing gets missed.