Upgrading to Java 17

This site is the new docs site currently being tested. For the actual docs in use please go to https://www.jenkins.io/doc.

When upgrading from JVM used to run Jenkins Java 11 to Java 17, there are some details you should know and precautions you should take.

Upgrading Jenkins Java Version From 11 to 17

Backing up Jenkins

As with any upgrade, we recommend:

  1. Backing up JENKINS_HOME.

  2. Testing the upgrade with your backup.

  3. Only after all required tests pass, performing the upgrade on your production instance.

Upgrading Jenkins

If you need to upgrade Jenkins, as well as the JVM, we recommend you:

  1. Back up JENKINS_HOME.

  2. Stop the Jenkins instance.

  3. Upgrade the JVM on which Jenkins is running.

    • Use a package manager to install the new JVM.

    • Ensure the default JVM is the newly installed version.

      • If it is not, run systemctl edit jenkins, and set either the JAVA_HOME environment variable or the JENKINS_JAVA_CMD environment variable.

  4. Upgrade Jenkins to the most recent version.

    • How you upgrade Jenkins is dependent upon your original Jenkins installation method.

      We recommend that you use the package manager of your system (such as apt or yum).

  5. Validate the upgrade to confirm that all plugins and jobs are loaded.

  6. Upgrade the required plugins. Refer to Upgrading Plugins for further information.

When upgrading the Java version for Jenkins and the JVM, it is important to upgrade all plugins that support Java 17. Plugin upgrades assure compatibility with the most recent Jenkins releases.

If you discover a previously unreported issue, please let us know. Refer to our issue reporting documentation for guidance.

JVM version on agents

All agents must be running on the same JVM version as the controller, due to how controllers and agents communicate. If you’re upgrading your Jenkins controller to run on Java 17, you must upgrade the JVM on your agents.

Validating the version of each agent can be done with the Versions Node Monitors plugin. This plugin provides information about the JVM version of each agent on the node management screen of your Jenkins instance. This plugin can also be configured to automatically disconnect any agent with an incorrect JVM version.