Liferay Upgrade Planner
Plan a Liferay upgrade from 6.2 or 7.x to DXP 2025.Q1 or 2026.Q1 LTS: breaking changes (incl. Jakarta EE), JDK, Tomcat and search requirements, and the database upgrade commands.
Choose your upgrade path
Liferay 7.4 → Liferay DXP 2024.Q (Quarterly)
(4 steps)DXP Quarterly releases (2024.Q1 onward) replace 7.4 updates with cumulative quarterly releases. The Q1 release each year is the Long-Term Support (LTS) release; the other quarters have shorter support, so most teams target the latest LTS.
Set liferay.workspace.product to a quarterly releaseKey from releases.liferay.com/releases.json so the bundle and BOM resolve against that release.
liferay.workspace.product=dxp-2024.q1.31
JDK 11 is deprecated in 2024.Q1, and 2024.Q2 and later certify JDK 17 and 21 and remove JDK 8. Move your runtime and builds to JDK 17 or, better, JDK 21.
2024 quarterly releases support Elasticsearch 7.17 and 8.8–8.19 through the bundled connector. Production must use a remote cluster.
Liferay DXP 2024.Q (Quarterly) → Liferay DXP 2025.Q1 LTS
(5 steps)2025.Q1 is a Long-Term Support release. Upgrade to its latest patch (for example 2025.Q1.28 LTS) rather than a Q2–Q4 release if you want the longest support window.
Point the Workspace at the 2025.Q1 LTS release, rebuild every module and fix compile errors from APIs removed since 2024.
liferay.workspace.product=dxp-2025.q1.28-lts
2025.Q1 certifies JDK 17 and JDK 21, with JDK 21 recommended. JDK 8 and 11 are no longer supported. Tomcat 9.0 is the certified Tomcat line.
2025.Q1 supports Elasticsearch 7.17 and 8.8–8.19, and adds OpenSearch 2 through the Liferay Connector to OpenSearch 2 from Marketplace (GA with OpenSearch 2.19 from 2025.Q1.23). Elasticsearch 7 is end of life and deprecated from 2025.Q2, so move to 8.19 or OpenSearch now.
2025.Q1 adds MySQL 8.4 and supports PostgreSQL 12–16. If you are still on MySQL 5.7, plan the move to 8.x now, because later releases deprecate it.
Liferay DXP 2025.Q1 LTS → Liferay DXP 2026.Q1 LTS
(8 steps)From 2026.Q1, Liferay ships one platform instead of separate Community Edition and DXP bundles. Community users get a free Activation Key (the Free Tier), and a subscription key can be added later without reinstalling. CE 7.4 GA users upgrade to this platform too.
Since 2025.Q3, Liferay runs on Jakarta EE 10, so 2026.Q1 is the first LTS where every javax.servlet, javax.portlet and similar import must become jakarta.*. Update the Workspace Gradle plugin to 14.0.0+ (17.1.7+ for matched Jakarta dependencies), run the upgradeJakarta task in each project, then review what it missed. Portlets move to Portlet 4.0.
# settings.gradle: com.liferay.gradle.plugins.workspace 14.0.0 or newer # gradle.properties: liferay.workspace.product=dxp-2026.q1.13-lts # In each project: blade gw upgradeJakarta
Add javaEEPackage: "jakarta" to each rest-config.yaml and regenerate the REST code.
# rest-config.yaml javaEEPackage: "jakarta" blade gw buildREST
Libraries you embed or deploy that use javax APIs need Jakarta versions (for example log4j-web becomes log4j-jakarta-web). Transforming jars with the Eclipse Transformer works but Liferay does not support applications built that way.
MySQL 5.7 and PostgreSQL 12 and 13 are deprecated in 2026.Q1. Use MySQL 8.0/8.4 or PostgreSQL 14–17.
2026.Q1 is certified only on Jakarta app servers: Apache Tomcat 10.1, JBoss EAP 8, Oracle WebLogic 15c and WildFly 30. Tomcat 9 does not run it. Start from the new bundle and carry your configuration over.
JDK 21 is the certified runtime for 2026.Q1. JDK 17 still works but is deprecated.
2026.Q1 ships a native Elasticsearch 8 connector that replaces the Elasticsearch 7 connector, and supports Elasticsearch 8.19.x. OpenSearch 2.19 is supported through the OpenSearch 2 connector 2.0.0 (GA from 2026.Q1.6). Elasticsearch 7 is not supported.
Database upgrade: Liferay 7.4 → Liferay DXP 2026.Q1 LTS
(9 steps)You do not install each version in between. The upgrade tool of the target release runs every upgrade step from your current schema in one go. The sections above list what changed along the way, so your code, themes and environment are ready for the target.
Take a full backup of the database, the Document Library store and [Liferay Home]/data. Run the upgrade on a copy of production first and time it. If an attempt fails, restore the backup instead of retrying on the same database.
Removing unused instances, sites, pages and old content versions can cut upgrade time considerably. Tune the database for a write-heavy batch and enable batch inserts in the upgrade tool.
Publications that are still open become read-only after the upgrade.
With the old server stopped and the new bundle configured against the database copy, run the upgrade client from [Liferay Home]/tools/portal-tools-db-upgrade-client. Before 7.4 U82/GA82 the script was called db_upgrade.sh. The default heap is 4 GB; give it more for databases over 10 GB, then read the upgrade report for errors.
cd [Liferay Home]/tools/portal-tools-db-upgrade-client ./db_upgrade_client.sh -j "-Xmx8192m"
Since 2025.Q3 the upgrade tool runs verification processes first and stops before changing anything if they fail. Fix what they report; only set upgrade.database.preupgrade.verify.enabled=false if a verifier blocks the upgrade by mistake.
If the report shows modules that did not finish, check and run their upgrade processes from Gogo Shell before allowing traffic.
upgrade:check upgrade:executeAll
Auto upgrade on startup is handy for local and test copies, but if you used it, remove upgrade.database.auto.run or set it to false before going live.
Connect the new search engine, then reindex all indexes (and the spell check indexes) from Control Panel → Search → Index Actions.
How to read this plan: the numbered sections list what changed in each release between your version and the target, so you can update code, themes and the environment in one go. The database is upgraded once at the end, straight to the target. Requirements were checked against Liferay's compatibility matrices and releases.json on 2026-10-12; confirm them for your exact patch level.
Upgrading Liferay 7.4 to Liferay DXP 2026.Q1 LTS
This plan covers the changes in 3 releases between Liferay 7.4 and Liferay DXP 2026.Q1 LTS, then one database upgrade, 26 steps in total. You don't install the versions in between: update your code, themes and environment for every change listed, then run the Liferay DXP 2026.Q1 LTS upgrade tool once against a backup of your database.
Releases in this path
- Liferay 7.4 → Liferay DXP 2024.Q (Quarterly) — 4 steps
- Liferay DXP 2024.Q (Quarterly) → Liferay DXP 2025.Q1 LTS — 5 steps
- Liferay DXP 2025.Q1 LTS → Liferay DXP 2026.Q1 LTS — 8 steps
Before you start
- Back up the database and the Document Library, and test the upgrade on a copy of production first.
- Patch your current version to its latest fix pack before beginning.
- Point your Liferay Workspace at the latest Liferay DXP 2026.Q1 LTS release:
liferay.workspace.product=dxp-2026.q1.13-lts. - Confirm JDK, app server and search engine requirements for your exact Liferay DXP 2026.Q1 LTS patch level. This plan was checked against Liferay's compatibility matrices on 2026-10-12.