Upgrading to Jakarta

Liferay DXP 2025.Q3+/Portal 2026.Q1+

Liferay stepped into the future of enterprise Java when it moved to Jakarta EE for the 2025 Q3 and the 2026 Q1 LTS release. This frees Liferay (and our users) to use the latest application servers and the most up to date libraries designed for the enterprise. These and future releases are all Jakarta-based, so if you have code that uses the old javax packages, you must modify that code—particularly its dependencies—to run on versions of Liferay that use the new Jakarta platform.

Thankfully, the process in most cases is straightforward and easy, and Liferay has provided tools to assist you. Liferay Workspace and Blade can help upgrade your projects to Jakarta.

There are three steps to upgrading a Liferay project to use Jakarta:

  1. Update Workspace and dependencies

  2. Run the Liferay source formatter on each project

  3. Replace third-party dependencies with their Jakarta counterparts

Update Workspace and Dependencies

Java-based web applications like portlets have dependencies on packages that were moved from the javax namespace to the jakarta namespace. Liferay’s source formatter can make many of these updates automatically, but you must use an up-to-date version of Workspace and the source formatter.

Update Liferay Workspace

You can set Workspace’s version by editing settings.gradle.

  1. In the root of your workspace, open settings.gradle in a text editor.

  2. Set the version to 13.0.11 at a minimum:

    dependencies {
      classpath group: "com.liferay", name: "com.liferay.gradle.plugins.workspace", version: "13.0.11"
    }
    
Tip

You can also configure Workspace to use whatever the latest version is:

dependencies {
  classpath group: "com.liferay", name: "com.liferay.gradle.plugins.workspace", version: "latest.release"
}

Next, update the target platform to a Jakarta-based version of Liferay:

  1. In the root of your workspace, open gradle.properties.

  2. Set the version to the Jakarta-based release you’re targeting, or 2025.q3.0 at a minimum:

    liferay.workspace.target.platform.version=2025.q3.0
    

Excellent! Workspace is configured for you to update your projects.

Update the Source Formatter

Liferay’s source formatter can examine your code for imports and convert dependencies Liferay knows about (i.e., ones shipped with Liferay) from javax to jakarta. This goes a long way toward upgrading your projects to Jakarta. To use it, you must make sure you use the proper version. If you’ve upgraded Workspace to 10.1.3 or greater, you have the right version of the source formatter. If you haven’t upgraded Workspace, you must update it to a version that supports Jakarta:

  1. Open the build.gradle file in one of your projects.

  2. Add the source formatter dependency above or below the Liferay dependency:

    sourceFormatter group: "com.liferay", name: "com.liferay.source.formatter", version: "1.0.1525"
    

    Use the version specified above or a greater version.

Awesome! You’re now ready to begin upgrading your project to Jakarta!

Run the Liferay Source Formatter

Now that Workspace is up to date and the source formatter is a dependency in your project, you can run the process.

  1. Drop to a CLI in the root of your project’s directory.

  2. Run the source formatter:

    blade gw formatSource -DformatSource.source.check.category.names="JakartaTransform,Upgrade" -DformatSource.java.parser.enabled=false
    

The source formatter has replaced every javax reference it can find in your Gradle, bnd.bnd, and your Java files with the appropriate jakarta reference. This handles dependencies that Liferay knows about. If you only have those, you’re ready to test! Compile, deploy, and test your project to be sure it works as expected. Note that some Jakarta APIs may differ from their javax counterparts. In those cases, you must make adjustments to your application.

If, however, you have dependencies on third-party .jars that don’t ship with Liferay, you have some more work to do to fix those dependencies.

Replace Third-Party Dependencies

Your final step in getting your project to compile (so you can test it) is to replace third-party .jars the source formatter couldn’t replace with their Jakarta counterparts. Here, Liferay can only give you guidance on how to proceed. There are three steps you can take, in order of most preferable to least preferable (and unsupported):

  1. Substitute a Jakarta-specific version of the .jar for the old javax version. If that’s not possible, find a replacement and modify your code to use it.

  2. If you have the original source code for the .jar, modify the source to replace javax with its Jakarta counterparts, and then build, test, and deploy the .jar.

  3. If you don’t have the source for the .jar, use the Eclipse Transformer to change any .jar dependent on javax classes to conform to the renamed Jakarta packages (unsupported, but may work).

Substitute or Replace Obsolete Jars with Jakarta Counterparts

There may be a Jakarta-specific version of the .jar you need. If that’s the case, your only step is to replace it in your project and then verify the imports and API calls work. This could be as simple as changing the dependency in your build script.

For example, Log4j has a legacy javax version you may have been using, with this dependency:

runtimeOnly "org.apache.logging.log4j:log4j-web"

To upgrade to the Jakarta version, you need only declare the Jakarta version and then fix the imports in your Java code:

runtimeOnly "org.apache.logging.log4j:log4j-jakarta-web"

Check the documentation for the .jars you’ve been using to see if a Jakarta-based replacement is available. If there isn’t one available, you have several other choices. It may be best to replace the .jar with another providing similar functionality and that also supports Jakarta. This option requires you to adapt your application to use the new functionality, but also ensures your application for the future.

If this is not possible, you still have two other options.

Modify the Original Jar’s Source

If you have the source code the .jar was compiled from and permission to modify the source (which is the case for open source projects), you can modify the original project’s source code to support Jakarta, recompile the .jar, and use it in your project.

This, of course, means you must now support this forked version of the .jar. Depending on what it does, this could be a better option than replacing it with something similar, or it could mean more work. You must decide which is best.

Either way, both of these options are better than the third option, which is unsupported, but may work as a last resort.

Use the Eclipse Transformer to Modify the Binary Jar

Your last option is to use the Eclipse Transformer to modify the binary .jar file to support Jakarta. You would only do this if you use a .jar that’s no longer maintained and that you don’t have the source code for.

This should be your last option, when all other options have been ruled out. Liferay doesn’t support errors resulting from transformed .jars; nor will whoever provided the original .jar.

If despite these warnings you still want to move ahead and use the Eclipse Transformer, you must use it with two properties files Liferay provides, which you can download from GitHub:

  1. Download the Eclipse Transformer from the link above.

  2. The Transformer is shipped as a .jar file you must unzip to use. Unzip the .jar file to its own folder.

  3. Download the two properties files above to the new Transformer folder.

  4. Copy the .jar file you want to transform to the same folder.

  5. Drop to a CLI in this folder.

  6. Run this command, substituting [name] for the name of the .jar file you’re transforming:

    java -jar org.eclipse.transformer.cli-1.0.0.jar --renames ./liferay-jakarta-renames.properties --versions ./liferay-jakarta-versions.properties ./[name].jar ./[name]-transformer.jar
    

The .jar is transformed. Whether it works is something you must test with your application. Note that Liferay cannot support applications with .jars that have been transformed this way.

Liferay has made many efforts to make the migration process to Jakarta as smooth and painless as possible. These tools can go a long way toward helping you successfully prepare your applications for the future.