Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 37 ยท Getting Started

Tomcat Versions and Java Compatibility

Understand which Tomcat release matches which Servlet API, Jakarta EE namespace and Java version, and how to choose a version and migrate from javax to jakarta.

Picking a Tomcat version is not only about "newest is best". Each release line implements a specific version of the Servlet specification, needs a minimum Java version, and, since Tomcat 10, uses a different Java package name for the whole web API. Choose wrongly and your application fails at startup with a ClassNotFoundException for javax.servlet.http.HttpServlet or jakarta.servlet.http.HttpServlet.

This lesson gives you the compatibility map, explains the big javax to jakarta rename, and shows how to decide which line to install. Version numbers below describe the release lines as of this writing; always confirm the exact patch release and support dates on the Apache Tomcat download and "which version" pages before you install.

The release lines

Tomcat line Specifications Namespace Minimum Java
9.0 Servlet 4.0, JSP 2.3, EL 3.0, WebSocket 1.1 (Java EE 8) javax.* 8
10.1 Servlet 6.0, JSP 3.1, EL 5.0, WebSocket 2.1 (Jakarta EE 10) jakarta.* 11
11.0 Servlet 6.1, JSP 4.0, EL 6.0, WebSocket 2.2 (Jakarta EE 11) jakarta.* 17

Older lines (8.5, 10.0) have reached end of life and receive no security fixes, so do not start new projects on them. Tomcat 10.0 was the first jakarta release but it was a short-lived transition line.

The pattern is simple: 9 is the last javax line, 10 and above are jakarta. Inside one line, patch releases (for example 10.1.x) only fix bugs and security problems and are safe to apply.

Choosing a Tomcat line

Tomcat 9 javax, Java 8+
Tomcat 10.1 jakarta, Java 11+
Tomcat 11 jakarta, Java 17+

New projects: pick 10.1 or 11.

1 / 2

Why javax became jakarta

Java EE was donated to the Eclipse Foundation and renamed Jakarta EE. The Oracle trademark rules meant the packages could no longer start with javax. Jakarta EE 9 renamed them to jakarta.* without changing behavior; later versions added features on top.

For you, the consequence is binary compatibility: a WAR compiled against javax.servlet does not run on Tomcat 10 or later, and a jakarta WAR does not run on Tomcat 9. Old libraries that call javax.servlet (some Struts or JSF versions, old filters) must be upgraded to a jakarta build.

Here is a tiny runnable program that models this decision. It stores the table above as data, then reports which Tomcat lines a project can use given its Java version and the namespace of its dependencies.

Java Which Tomcat lines fit my project? (stand-in decision tool)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Moving an application from javax to jakarta

There are three ways to migrate, from cheapest to most thorough.

  1. Stay on Tomcat 9 until you are ready. Fine for a while, but plan the move.
  2. The Tomcat migration tool. Tomcat ships migration-tool-for-jakartaee, which rewrites a WAR's classes, web.xml and libraries from javax to jakarta. You can also drop a javax WAR into the webapps-javaee folder of a Tomcat 10 and the auto-conversion feature converts it on deployment. This is meant for testing and transitions, not as a permanent production setup.
  3. Rewrite the imports. The source change is mechanical:
Java
// Before (Tomcat 9)
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;

// After (Tomcat 10 and later)
import jakarta.servlet.http.HttpServlet;
import jakarta.servlet.http.HttpServletRequest;

Only javax.* packages that belong to Jakarta EE are renamed. javax.sql, javax.net.ssl, javax.crypto and other packages that are part of the Java SE platform stay as they are, so a blind search-and-replace of javax. is wrong.

The next program shows exactly that rule: it rewrites a list of import lines and leaves the Java SE ones alone.

Java Rewrite imports the careful way

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Also check deployment descriptors: the XML namespace in web.xml changes from http://xmlns.jcp.org/xml/ns/javaee (Servlet 4) to https://jakarta.ee/xml/ns/jakartaee (Servlet 5 and later). Tomcat 10 and later still accept old descriptors in some cases, but update them so tools validate your file.

Checking what you run

When Tomcat starts, the first lines of logs/catalina.out (or the console) print the server version, build date, OS and JVM. You can query the same data on a running server with the version command of the launch script, as covered in starting and stopping Tomcat:

TEXT
$ bin/catalina.sh version
Server version: Apache Tomcat/10.1.x
Server number:  10.1.x.0
JVM Version:    21.0.x

(The exact numbers depend on your installation.) Inside a running application, ServletContext#getMajorVersion() and getMinorVersion() report the Servlet API level the container implements.

A practical decision rule

  • New project: choose Tomcat 10.1 (broad library support) or 11 (newest specs and Java 17+). Use the latest patch release.
  • Existing javax application you cannot change soon: keep Tomcat 9, apply security patches, and schedule the migration.
  • Spring Boot: the embedded Tomcat version is chosen by the Spring Boot release (Spring Boot 3 and later use jakarta). You normally do not install Tomcat yourself.
  • Always use a Java version your Tomcat line supports and that still receives updates (an LTS release such as 17 or 21).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which Tomcat line is the last one that uses the javax.servlet package?

    Tomcat 9 implements Servlet 4.0 with javax.. Tomcat 10 and later use jakarta..
  2. 2. What happens if you deploy a WAR built against javax.servlet on Tomcat 10.1 without converting it?

    The binary names differ, so classes referencing javax.servlet cannot be linked. You need to migrate the code or use the migration tool.
  3. 3. Which import must NOT be changed to jakarta when migrating?

    javax.sql is part of Java SE, not Jakarta EE, so it keeps its name. Only the Jakarta EE packages were renamed.
  4. 4. What is the minimum Java version listed for Tomcat 11?

    Tomcat 11 requires Java 17 or later; Tomcat 10.1 needs 11, and Tomcat 9 needs 8.

Summary

  • Tomcat 9 = Servlet 4.0, javax, Java 8+; Tomcat 10.1 = Servlet 6.0, jakarta, Java 11+; Tomcat 11 = Servlet 6.1, jakarta, Java 17+.
  • The javax to jakarta rename breaks binary compatibility, so WARs and libraries must match the Tomcat line.
  • Migrate with the Tomcat migration tool or by renaming imports, but only for Jakarta EE packages.
  • New projects should use a supported jakarta line on an LTS Java.
  • Always apply the latest patch release of your line and check the official support dates.

Next: Your first web application