Skip to content
Tutorials Center
My learning

Topics

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.

Rust
#[deprecated(since = "1.2.0"1.2.0", note = "use `new_fn` instead"use `new_fn` instead")]
fn old_fn() {}

Try it

Rust Deprecating a function

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.

Rust Deprecated items and silencing the lint

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

Rust
#[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 since and note.