Spring 6 to 7: Key Changes & Upgrade Checklist

Spring Framework 7.0, released in November 2025, is a major upgrade that requires Java 17 or later and introduces a new baseline for enterprise Java development. The most critical change is that Spring 7 is built on and requires Jakarta EE 11, meaning you must update all javax.* imports to jakarta.* and ensure your application server or servlet container supports the new specification. This article details the key differences between Spring 6 and 7, then provides a safe, step-by-step upgrade checklist to minimize risk.

Formula

The calculator above gives a rough upgrade risk score and effort estimate based on the number of modules you maintain and the number of breaking changes you anticipate. The formula is:

Risk Score = min(100, (Breaking Changes × 10) + (Modules × 5))

Estimated Effort (hours) = (Breaking Changes × 4) + (Modules × 2)

Where:

• Modules – the number of Spring-based modules or libraries in your project (e.g., spring-web, spring-data, your own modules).
• Breaking Changes – the number of API changes or removals that affect your codebase. You can estimate this by reviewing the Spring Framework 7 migration notes or running a dependency analysis tool.

The risk score is capped at 100 for simplicity. The effort estimate assumes each breaking change takes about 4 hours to fix and each module requires 2 hours of testing and adjustment.

Worked Example

Suppose you have a typical microservice with 3 modules (web, service, data) and you expect 5 breaking changes based on the migration guide. Using the defaults from the calculator:

1. Risk Score = min(100, (5 × 10) + (3 × 5)) = min(100, 50 + 15) = 65
2. Effort = (5 × 4) + (3 × 2) = 20 + 6 = 26 hours

So you’d get a risk score of 65 and an estimated effort of 26 hours. This is a rough planning tool, not a precise prediction – actual effort depends on your codebase complexity and team familiarity.

Background: Why Spring 7 Exists

Spring Framework 6.0, released in November 2022, was a major milestone because it introduced support for Jakarta EE 9 (the new namespace for Java EE) and required Java 17. Spring 7, released in November 2025, builds on that by requiring Jakarta EE 11, which includes Servlet 6.1, JPA 3.2, and Bean Validation 3.1. The core motivation is to align with the latest enterprise Java specifications, enabling better performance, security, and support for modern cloud-native development.

Another key driver is the shift toward virtual threads (Project Loom), which became stable in Java 21. Spring 7 fully embraces virtual threads, making it easier to write high-throughput concurrent applications without the complexity of reactive programming. This is a significant departure from Spring 6, where virtual threads were still experimental and required manual configuration.

Key Changes from Spring 6 to 7

Here are the most impactful changes you need to know before upgrading:

• Java 17 is the minimum, Java 21 recommended – Spring 7 requires Java 17 as a baseline, but Java 21 is the recommended runtime because it includes virtual threads and other features Spring 7 exploits.
• Jakarta EE 11 namespace – All javax.* imports (e.g., javax.servlet, javax.persistence) must be replaced with jakarta.* (e.g., jakarta.servlet, jakarta.persistence). This is a mechanical but widespread change.
• Virtual threads by default – Spring 7 automatically uses virtual threads for request handling when running on Java 21+. You can opt out with a property, but the default is on.
• Removal of deprecated APIs – Many deprecated methods and classes from Spring 5/6 have been removed. For example, MockMvc builders and WebMvcConfigurerAdapter are gone; you must use the newer interfaces.
• Observability improvements – Spring 7 integrates more deeply with Micrometer Tracing, providing better distributed tracing support out of the box.
• HTTP client changes – The RestClient (introduced in Spring 6.1) becomes the preferred way to make HTTP calls, and some older RestTemplate methods are deprecated.
• Modularization – Spring 7 has split some modules further, so you may need to add new dependencies (e.g., spring-webmvc is now separate from spring-web).

How to Upgrade Safely: Step-by-Step Checklist

Upgrading a major framework version is risky, but you can mitigate it with a disciplined approach. Follow this checklist:

1. Read the official migration guide – Start with the Spring Framework 7 Migration Guide (available on the Spring website). It lists every breaking change and provides code snippets for fixes.
2. Check your Java version – Ensure your build environment and runtime use Java 17 or later. If you’re on Java 11 or lower, upgrade Java first.
3. Update all dependencies – Use a dependency management tool (Maven or Gradle) to update Spring Framework to 7.0.x, and also update related projects like Spring Boot (to 4.0.x), Spring Security (to 7.0.x), and Spring Data (to 2025.x).
4. Replace javax with jakarta – Do a global search-and-replace for javax. to jakarta. in your Java sources, but be careful: some packages like javax.annotation are now jakarta.annotation, but not all (e.g., javax.sql remains javax.sql). Use your IDE’s refactoring tool to do this safely.
5. Update your servlet container – If you use Tomcat, Jetty, or Undertow, upgrade to a version that supports Servlet 6.1 (e.g., Tomcat 11). Check your deployment environment supports it.
6. Fix removed APIs – Compile your code and fix any errors related to removed methods or classes. The compiler will guide you, but you may need to consult the migration guide for replacements.
7. Test thoroughly – Run your full test suite, including integration tests. Pay special attention to anything that uses threading, because virtual threads can change behavior (e.g., thread-local variables may behave differently).
8. Monitor performance – After deployment, monitor for regressions. Virtual threads can improve throughput but may also expose issues like thread-safety problems in your code.

Common Problems and How to Solve Them

During upgrade, you’ll likely hit these issues:

• ClassNotFoundException for javax.* – This means you missed some imports. Use your IDE’s “Find Usages� to locate all javax references.
• Bean creation errors due to circular dependencies – Spring 7 is stricter about circular dependencies. Refactor your beans to break the cycle, often by using @Lazy or redesigning.
• Virtual thread issues – If you use ThreadLocal extensively, virtual threads may cause memory leaks because they are reused. Switch to ScopedValue (Java 21+) or adjust your code.
• Missing dependencies – Spring 7 modularization means you might need to add new artifacts. Check your Maven/Gradle dependencies against the official BOM.

Costs and Effort

The upgrade effort varies widely. A small application with few dependencies might take a day, while a large enterprise system with many custom modules could take weeks. The main costs are:

• Developer time – Fixing imports, API changes, and testing.
• Infrastructure updates – Upgrading application servers, CI/CD pipelines, and possibly cloud environments to support Jakarta EE 11 and Java 21.
• Training – Developers need to learn new APIs and features like virtual threads.

There’s no monetary license cost – Spring is open-source – but the opportunity cost of not upgrading is staying on an older, less supported version.

Alternatives to Upgrading

If you’re not ready for Spring 7, you have a few options:

• Stay on Spring 6 – Spring 6.2.x will receive support for a while (check the official support timeline). You can still get security patches.
• Use Spring Boot 3.x – Spring Boot 3.5+ uses Spring 6.2, which is a stable, well-tested combination. You can delay the move to Spring Boot 4 / Spring 7.
• Consider alternative frameworks – If you’re starting a new project, you might evaluate Micronaut or Quarkus, which also support Jakarta EE 11 and virtual threads, but they have different programming models.

However, staying on older versions means you’ll miss out on security fixes and new features, so plan a migration eventually.

Frequently Asked Questions

Is Spring 7 backward compatible with Spring 6?

No, Spring 7 is not fully backward compatible. Many deprecated APIs were removed, and the namespace change from javax to jakarta is a breaking change. You must modify your code, though the changes are mostly mechanical.

Do I need to upgrade to Spring Boot 4 to use Spring 7?

Yes, Spring Boot 4.0 is built on Spring Framework 7. If you use Spring Boot, you must upgrade to Boot 4.0 to get Spring 7. You cannot mix Spring Boot 3.x with Spring 7.

What Java version do I need for Spring 7?

Spring 7 requires Java 17 as a minimum. For the best experience, especially with virtual threads, use Java 21 or later. Java 17 is supported but virtual threads won’t be available.

Can I run Spring 7 on Tomcat 10?

No, Tomcat 10 implements Servlet 5.0, which is Jakarta EE 9, not 11. You need Tomcat 11 or another servlet container that supports Servlet 6.1.

Will my existing Spring Data repositories work in Spring 7?

Yes, but you need to upgrade Spring Data to the version that supports Spring 7 (e.g., Spring Data 2025.x). The repository interfaces remain largely the same, but you may need to adjust for JPA 3.2 changes.

How do I test for virtual thread compatibility?

Run your application on Java 21 with Spring 7 and enable virtual threads. Use load testing to see if thread-safety issues arise. Also, check for any code that uses synchronized blocks or ThreadLocal – these can be problematic with virtual threads.

Related

• Live Service Games: Developer Concerns Explained
• Hybrid Work Schedule: 12 Tips That Actually Work
• College Recruitment Games: Mobile-Friendly Essentials

in t | modules | Number of modules | 1 | 1 | 100
in t | breaking_changes | Breaking changes found | 5 | 0 | 100
out score | Upgrade risk score | /100 | min(100, (breaking_changes * 10) + (modules * 5)) | 0
out effort | Estimated effort (hours) | h | breaking_changes * 4 + modules * 2 | 0