Rust Reference ยท Attributes
The #[deprecated] attribute
Reference for Rust #[deprecated]: the since and note fields, which items accept it, the deprecated lint, and how to migrate callers without breaking them.
#[deprecated] marks an item as one you no longer recommend. Code that uses it still compiles, but the compiler emits a deprecated warning at each use, and rustdoc shows a deprecation notice. It is how a library retires an API gradually, without a breaking change.
You can attach a version and a note that explains the replacement. The warning appears where the item is used, not where it is defined.
#[deprecated(since = "1.2.0"1.2.0", note = "use `new_fn` instead"use `new_fn` instead")] fn old_fn() {}
Try it
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::stdin().read_line()), it gets the next line from this box.
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::stdin().read_line()), it gets the next line from this box.
Syntax
#[deprecated] #[deprecated = "note text"] #[deprecated(since = "1.2.0"1.2.0", note = "use something else"use something else")]
| Field | Description |
|---|---|
since |
The version in which the item was deprecated (a string; informational) |
note |
A message shown in the warning and in the docs; name the replacement here |
It can be placed on functions, methods, structs, enums and their variants, fields, constants, statics, type aliases, traits, modules, macros and use items in some forms.
Edge cases:
- Uses inside the deprecated item itself and inside other deprecated items do not warn.
- Implementing a deprecated trait or calling a deprecated trait method through a generic bound warns at the implementation or call.
- The standard library also uses
#[deprecated(since = "...", note = "...")]for old APIs, plus a separate scheme (deprecated_in_future) for items scheduled to be deprecated later.
Usage notes
- Always give a note. A warning that names the replacement saves readers a search.
- Keep the old behaviour. A deprecated item should keep working as before; changing semantics silently is a breaking change in disguise.
- Silence per call site with
#[allow(deprecated)]while migrating, and remove the attribute once done. - Remove in a major version. The usual policy is to keep deprecated items for at least one release cycle before deleting them in a semver-major release.
- Lint level.
#![deny(deprecated)]turns every use into an error, which is useful in CI after a migration is complete. - Documentation. rustdoc adds a prominent "Deprecated" box using your
sinceandnote.