Migrate from Tomcat 9 to Tomcat 10.1

What changed

Oracle handed Java EE to the Eclipse Foundation, which renamed it Jakarta EE. Starting with Jakarta EE 9, every package moved from javax.* to jakarta.*. So javax.servlet.http.HttpServlet became jakarta.servlet.http.HttpServlet. Tomcat 10 and later implement the new names only. Tomcat 9 stays on javax.* and is still maintained.

Only the Jakarta EE namespaces moved. JDK packages such as javax.crypto, javax.net or javax.sql keep their names.

Do you need to migrate?

Not immediately. If your application is stable and you can keep Tomcat 9 patched, staying is a legitimate choice. Migrate when you need a newer framework (Spring Framework 6 and Spring Boot 3 require jakarta.*), newer Java features or a long-term supported base.

Option 1: the Tomcat migration tool (quick test)

Apache provides a command line tool that rewrites a WAR for Tomcat 10. It is also available as a drop-in: put a WAR in /opt/tomcat/webapps-javaee/ and Tomcat converts it on deployment.

# download the migration tool from the Tomcat downloads page, then:
java -jar jakartaee-migration-*-shaded.jar old-app.war new-app.war

Treat it as a way to find out whether your application works, and as a bridge. It converts class files and descriptors, but not libraries that you load by reflection or that carry their own javax references. Test everything.

Option 2: change the source (the lasting fix)

1. Dependencies first: move every Java EE library to its Jakarta version, for example Hibernate 6, Spring Framework 6, Jackson, Jersey 3 or newer, JSTL from jakarta.servlet.jsp.jstl. A library that has no Jakarta release is the real blocker: find a replacement.
2. Imports: replace javax.servlet, javax.persistence, javax.annotation, javax.inject, javax.validation, javax.ws.rs, javax.mail and so on with jakarta.*. IntelliJ's migration refactoring, OpenRewrite recipes (org.openrewrite.java.migrate.jakarta.JavaxMigrationToJakarta) and a careful search and replace all work.
3. XML: update the namespaces in web.xml, persistence.xml, beans.xml and the schema versions (for example https://jakarta.ee/xml/ns/jakartaee, version 6.0 for web.xml).
4. JSP and tag libraries: change http://java.sun.com/jsp/jstl/core style URIs to jakarta.tags.core, and the imports inside scriptlets.
5. Java version: make sure the server runs Java 11 or newer, and ideally 17 or 21.

Test on a second server first

Do not upgrade in place. Install Tomcat 10.1 next to Tomcat 9 on another port or another server, deploy the migrated build, and test the pages and flows that matter: login, forms, file upload, database writes, scheduled jobs and mail. Check the log for ClassNotFoundException: javax. or NoClassDefFoundError for jakarta classes, which point to a library you missed. When it is right, switch the proxy over. Keep the old server for a day or two to roll back.

Install steps: Install Tomcat on Ubuntu. On Tomcat hosting plans we can run both versions side by side while you migrate; managed plans include help migrating one application.

Last updated October 29, 2026.