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 6.2 → Liferay 7.0
(8 steps)Catalog all hook, ext, theme, layout, and portlet plugins. Each maps to a different OSGi extension point in 7.x, so this list becomes your migration backlog. Anything not on the list will silently stop working.
The Ant-based Plugins SDK is gone. Recreate your projects in a Liferay Workspace and build with Gradle/Blade. Use Blade CLI to scaffold modules and to convert existing plugins where possible.
blade init my-workspace cd my-workspace blade convert -s my-old-plugin
Hook and Ext plugins no longer exist. Each customization becomes an OSGi component at a specific extension point — ServiceWrapper, ModelListener, DynamicInclude, MVCActionCommand, OSGi Configuration, etc. Map each one before writing code.
Hook vs OSGi Decision TreeVelocity (.vm) templates were deprecated in 7.0 and later removed, so 7.4 and DXP only run FreeMarker (.ftl). Port portal_normal.vm, navigation.vm, ADTs and web content templates to .ftl, and rebuild themes with the Node/Gulp theme tooling.
Velocity to FreeMarker ConverterThe monolithic portal-service API was split into hundreds of app modules. Many com.liferay.portal.kernel.* classes moved to their owning module APIs. Expect to fix imports across the whole codebase and declare the new module dependencies.
*LocalServiceUtil facades still exist for compatibility, but in OSGi modules you should inject services with @Reference. Regenerate Service Builder code against 7.0 and review service.xml for changes.
service.xml GeneratorEmbedded Lucene is replaced by Elasticsearch. The embedded ES mode is for development only; production requires a separate Elasticsearch cluster configured via the OSGi search connector settings.
Liferay 7.0 requires JDK 8 and a current app server (e.g. Tomcat 8). Update your runtime and JVM before deploying.
Liferay 7.0 → Liferay 7.1
(4 steps)More configuration is exposed as typed OSGi configuration in System Settings / Instance Settings. Review portal-ext.properties for keys that are now managed in the UI or via .config files.
OSGi Config GeneratorThe Lexicon/Clay component set is the standard for 7.1 UI. AlloyUI is on the way out — start migrating custom widgets toward Clay markup and tags.
Compile your modules against 7.1 and address deprecation warnings now; several 7.0-deprecated methods are removed in later releases.
Liferay 7.1 supports Elasticsearch 6.1–6.8 (and Elasticsearch 7 through the Liferay Connector to Elasticsearch 7 on later patches). Elasticsearch 2.x from early 7.0 is not supported.
Liferay 7.1 → Liferay 7.2
(3 steps)Update the liferay.workspace.target.platform.version in gradle.properties so BOM-managed dependency versions resolve against 7.2.
liferay.workspace.target.platform.version=7.2.1-1
Methods deprecated back in 7.0/7.1 are removed in 7.2. Rebuild every module against the 7.2 target platform and fix any unresolved references.
Liferay 7.2 supports Elasticsearch 6.5–6.8, and Elasticsearch 7 through the Elasticsearch 7 connector depending on patch level. Confirm your cluster matches before upgrading.
Liferay 7.2 → Liferay 7.3
(3 steps)Several core apps were rewritten on React with Clay 3. If you customized their JSPs or markup, re-validate those customizations against the new front end.
Liferay 7.3 dropped Elasticsearch 6. Provision an Elasticsearch 7.9–7.17 cluster (later 7.3 updates also support 8.x) and reconnect the search connector.
7.3 supports both JDK 8 and JDK 11. If you plan to move to JDK 11, test module compilation and any reflection-heavy code under it now.
Liferay 7.3 → Liferay 7.4
(5 steps)7.4 consolidated many apps and introduced Objects and an expanded headless API. Recompile all modules against the 7.4 target platform and review any custom entities that overlap with Objects.
More legacy properties were removed or moved to OSGi configuration in 7.4. Diff your portal-ext.properties against the 7.4 defaults and migrate anything that no longer applies.
Portal Properties DiffAPIs deprecated across the 7.x line are removed in 7.4. Rebuild and fix any remaining references before deploying.
Liferay 7.4 runs on JDK 8 and JDK 11. Standardize your build and runtime on JDK 11 now, because the quarterly releases remove JDK 8 and move on to JDK 17 and 21.
Liferay 7.4 supports Elasticsearch 7.14–7.17, and Elasticsearch 8.8+ on later updates (DXP U81+, CE GA102+). Elasticsearch 7 is end of life, so moving to 8.x now saves a step later.
Database upgrade: Liferay 6.2 → Liferay 7.4
(8 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.
6.2.0 is the minimum starting point for a direct upgrade. 6.1 can upgrade directly only with feature.flag.LPS-157670=true in portal-ext.properties, and 5.x or 6.0 must upgrade to 6.2 first. Patch 6.2 to its latest fix pack or service pack before you begin.
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.
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"
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.
After the upgrade, reindex all search indexes from Control Panel → Search so content is searchable again.
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.
Plan Any Liferay Upgrade Path
Liferay upgrades the database directly from 6.2 or any 7.x release to the target, but your code, themes and environment still have to absorb every change in between. This planner lists those changes release by release, from the OSGi jump at 7.0 to the Jakarta EE, Tomcat 10.1 and JDK 21 move in 2026.Q1 LTS, and finishes with the one database upgrade and its commands.
Last checked against Liferay's compatibility matrices and releases.json on 2026-10-12.
Supported Versions
Popular Upgrade Paths
How to Use This Planner
- Select your current and target versions. The URL updates so you can bookmark or share the exact path.
- Work through the changes. Each numbered section is one release's changes, with steps ordered pre-flight → breaking → deprecated → data upgrade → tooling.
- Run the database upgrade once. The last section is the direct upgrade to your target, with the backup, upgrade tool, Gogo Shell and reindex steps.
- Filter by category to focus on, say, only breaking changes or only data-upgrade steps.
- Tick off steps as you complete them and watch the progress bar.
- Export the plan as Markdown to drop into a Jira ticket or upgrade runbook.
Frequently Asked Questions
- Do I have to upgrade through each major version?
- No. Liferay supports upgrading the database directly from Liferay Portal 6.2.0 or later to the latest release, so you run the target release's upgrade tool once. 6.1 can upgrade directly with feature.flag.LPS-157670=true, and 5.x or 6.0 must go to 6.2 first. Your code still has to absorb every change in between, which is why the planner lists the changes per release and then one database upgrade.
- Should I upgrade to 2025.Q1 LTS or 2026.Q1 LTS?
- 2026.Q1 is the newest LTS, but it runs on Jakarta EE, Tomcat 10.1, JDK 21 and Elasticsearch 8.19 or OpenSearch 2.19, so custom modules need the javax to jakarta migration. 2025.Q1 LTS is still on Java EE and Tomcat 9, so it is the smaller step if you need to upgrade soon and migrate to Jakarta later.
- What changed for Community Edition users?
- From 2026.Q1 Liferay ships one platform instead of separate CE and DXP bundles. Community users request a free Activation Key (the Free Tier), and can add a subscription key later without reinstalling. Users on CE 7.4 GA132 plan their upgrade like a 7.4 to 2026.Q1 move.
- Why is the 6.2 to 7.0 jump so much bigger?
- Liferay 7.0 introduced the OSGi module framework, replaced hooks and ext plugins with OSGi extension points, switched themes from Velocity to FreeMarker, reorganized the API into app modules, and moved search to Elasticsearch. It is the largest single change, which is why it has the most steps.
- What are the step categories?
- Pre-flight (do before you start), Breaking Change (code or configuration that must change), Deprecated / Removed (APIs and versions to stop using), Data Upgrade (database and content migration), and Tooling / Environment (JDK, app server, search engine, database). Within each section the planner orders steps in that sequence.
- Is this an official, exhaustive upgrade guide?
- No. It is a checklist of the most important steps for planning and scoping an upgrade. Requirements were checked against Liferay's compatibility matrices and releases.json; always confirm them for your exact patch level and test on a copy of production first.
- Can I export the checklist?
- Yes. Tick off steps as you complete them, then use Copy as Markdown or Download .md to paste the plan, including your progress, into a ticket or runbook.
Related Liferay Tools
- Hook vs OSGi Decision Tree
Pick the 7.x extension point for each 6.2 hook.
- Velocity to FreeMarker Converter
Convert 6.2 Velocity themes and templates to FreeMarker.
- Portal Properties Diff
Compare portal properties between versions.
- Theme Builder Wizard
Generate a 7.4+ theme or Theme CSS client extension.