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:

Update Workspace and dependencies
Run the Liferay Jakarta upgrade tool on each project
Replace third-party dependencies with their Jakarta counterparts

Update Workspace

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

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

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

Set the version to 14.0.0 at a minimum:

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

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:

In the root of your workspace, open gradle.properties.
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.

Run the Jakarta Upgrade Tool

Workspace includes a Jakarta upgrade tool that can examine your code 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, but be aware of these things:

This tool modifies your project files directly.
After running the tool, you must review your code for missed references that require manual updates.

Once Workspace is up to date, run the Jakarta upgrade tool.

Warning

The Jakarta upgrade tool upgrades portlet code to Jakarta Portlet 4.0 in addition to general javax references. If you attempt to update your code references manually, you must update all the references in the Jakarta Portlet 4.0 upgrade changes, too.

Drop to a CLI in the root of your project’s directory.
Run the Jakarta upgrade tool:
```
blade gw upgradeJakarta
```

The tool has replaced every javax reference it can find in your Gradle, bnd.bnd, and 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.

Jakarta Portlet Upgrade Changes

When you run the Jakarta upgrade tool to upgrade your code references to Jakarta, it also upgrades your portlet code from using Portlet 3.0 to Jakarta Portlet 4.0. If you don’t run the tool, you must manually update these references in your code.

The Jakarta upgrade tool changes these portlet references:

Javax Portlet 3.0	Jakarta Portlet 4.0	File Context
`javax.portlet.*`	`jakarta.portlet.*`	Package names
`javax.portlet.version=3.0`	`jakarta.portlet.version=4.0`	`@Component` properties
`<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">`	`<web-app version="6.0" xmlns="https://jakarta.ee/xml/ns/jakartaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-app_6_0.xsd">`	`web.xml` (switch to servlet 6.0)
`<web-fragment version="3.0" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-fragment_3_0.xsd">`	`<web-fragment version="6.0" xmlns="https://jakarta.ee/xml/ns/jakartaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-fragment_6_0.xsd">`	`fragment.xml` (switch to servlet 6.0)
`<taglib version="2.1" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-jsptaglibrary_2_1.xsd">`	`<taglib version="3.0" xmlns="https://jakarta.ee/xml/ns/jakartaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-jsptaglibrary_3_0.xsd">`	Taglib modules

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 Jakarta upgrade tool couldn’t replace with their Jakarta counterparts. Here, Liferay can only give you guidance on how to proceed. There are two steps you can take; the first is preferable and supported, but the second is an unsupported last resort:

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.
If there’s no suitable Jakarta replacement for the dependency, 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 one other option. It’s 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 issues resulting from transformed .jars; nor will the provider ofthe 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:

Download the Eclipse Transformer from the link above.
The Transformer is shipped as a .jar file you must unzip to use. Unzip the .jar file to its own folder.
Download the two properties files above to the new Transformer folder.
Copy the .jar file you want to transform to the same folder.
Drop to a CLI in this folder.

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.