Using @Deprecated in Java to Manage API Evolution
Learn how to use Java's @Deprecated annotation to mark outdated APIs, manage compiler warnings, and plan API removal.

The @Deprecated annotation in Java tells developers and tools that a method, class, or field should no longer be used. It does not remove the code; it marks it for eventual replacement. Understanding how @Deprecated behaves helps you manage API evolution without breaking existing callers.
What @Deprecated Actually Does
@Deprecated is a marker annotation that triggers a compiler warning when the annotated element is used in source code. The Java compiler emits a warning that appears in the build output, and most IDEs highlight the usage visually. The annotation itself has no effect at runtime; it does not prevent invocation or throw an exception. Its purpose is to communicate to developers that a better alternative exists and that the old API may be removed in a future release.
The warning is a compile-time signal, not a runtime restriction. You can still call a deprecated method, but the compiler will remind you that the call is against the current guidance. This is useful for library maintainers who need to keep backward compatibility while steering users toward newer APIs.
Declaring a Deprecated Method or Class
To deprecate a method, place @Deprecated directly before the declaration. For example:
public class LegacyApi {
/**
* Old method, use {@link #newMethod()} instead.
* @deprecated since 2.0, use newMethod() instead.
*/
@Deprecated
public void oldMethod() {
// implementation
}
public void newMethod() {
// replacement implementation
}
}The annotation alone is enough to produce a warning. However, you should also add the Javadoc @deprecated tag (lowercase) to document the reason and the replacement. The Javadoc tool uses this tag to render a deprecated notice in the generated documentation. The annotation and the tag are separate: the annotation controls compiler warnings, while the tag controls documentation.
You can also deprecate a class, interface, field, constructor, or enum constant. The same rules apply: the annotation triggers warnings on any reference to that element.
Suppressing Deprecation Warnings
Sometimes you must call a deprecated method because no replacement exists yet, or because you are maintaining code that targets an older version. In that case, you can suppress the warning locally with @SuppressWarnings("deprecation"). This annotation can be placed on the enclosing method, class, or even a local variable declaration. For example:
@SuppressWarnings("deprecation")
public void runLegacy() {
LegacyApi api = new LegacyApi();
api.oldMethod(); // no warning emitted
}Be careful with broad suppression. Applying it to a whole class hides all deprecation warnings in that class, which can obscure future deprecations you might need to address. Prefer the narrowest scope: suppress on a single method when possible. If you are a library author, avoid suppressing warnings in your own public API; you want your users to see them.
Using forRemoval and since Attributes
Java 9 introduced two optional attributes for @Deprecated: since and forRemoval. The since attribute records the version in which the element was deprecated. The forRemoval attribute signals that the element is intended for removal in a future release. The compiler treats these differently:
@Deprecated(since = "2.0", forRemoval = true)
public void legacyMethod() {
}When forRemoval is true, the compiler emits a stronger warning, often called a removal warning. Many build tools and IDEs display this with a different style or severity. The Javadoc also marks it with a special notice. This attribute is a clear signal that the API is on a removal path and should be migrated as soon as possible.
The since attribute is informational; it does not change compiler behavior. It helps developers judge how long the API has been deprecated and whether they need to act quickly. The attributes are available only when compiling with Java 9 or later; older compilers do not recognize since or forRemoval on @Deprecated.
Documenting the Replacement in Javadoc
The @deprecated Javadoc tag is the place to explain why the API is deprecated and what to use instead. Always include a link to the replacement using {@link}. For example:
/**
* Returns the legacy format.
*
* @deprecated since 3.1, use {@link #formatNew()} instead.
* The legacy format does not support time zones.
*/
@Deprecated(since = "3.1")
public String formatLegacy() { ... }
public String formatNew() { ... }This documentation appears in the generated API documentation and in IDE hover tips. Without it, developers see a warning but may not know what to do. The combination of the annotation and the Javadoc tag gives both the compiler signal and the human-readable guidance.
Deprecation and Binary Compatibility
Deprecation does not break binary compatibility. A deprecated method still exists in the compiled class file and can be called by code compiled against it. Removing the method later is a breaking change. @Deprecated does not change the method's executable code or runtime behavior; it is a compile-time signal that is recorded in the class file.
This is important for library maintainers. You can deprecate an API in one release and still keep it for several releases to give users time to migrate. The forRemoval attribute signals that you plan to remove it, but the actual removal is a separate decision. When you do remove it, you must bump the major version according to semantic versioning, and you should document the removal clearly in the release notes.
Common Mistakes and Edge Cases
One common mistake is deprecating a method but continuing to use it inside the same library. This creates warnings in your own build and confuses users who see the library itself using deprecated code. If you must keep the old implementation for internal use, consider making it private or extracting the logic to a non-deprecated helper.
Another edge case is deprecating a method that overrides a method from a superclass. The @Deprecated annotation is not inherited. If a superclass method is deprecated, overriding it without the annotation does not make the override deprecated. Conversely, deprecating an override does not deprecate the superclass method. You need to annotate each declaration explicitly.
Finally, remember that @Deprecated is a compile-time hint. Reflection can read it via getAnnotation(Deprecated.class), but that is rarely useful in production code. The annotation does not affect serialization, reflection invocation, or any runtime check. Rely on it only for developer communication and compiler warnings, not for enforcing policy at runtime.
Try matching browser tools
All toolsSmall utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Java guides
All Java guidesJava Final Keyword: Usage and Behavior
How Java's final keyword works for variables, methods, and classes, with practical examples and decision guidance for using it.
Java Final Variable: Syntax, Behavior, and Use Cases
Understand what a final variable in Java means, how initialization works, and when to use it for constants, immutability, and clearer code.
Java Duration vs Period: When to Use Each
java duration vs period: Compare Java Duration and Period to handle time-based and date-based calculations correctly. Learn syntax, conversion, and pitfalls.
Instance vs Static Variables in Java: Key Differences
Understand the difference between instance and static variables in Java, including memory, lifecycle, and when to use each.
More in Java
All Java guidesThe guides filed next to this one in Java, in library order.