How to deprecate a function in Python, JS, Java, Go, Rust
8 min read
To deprecate a function, keep it working and mark it with your language’s deprecation marker, so every caller gets a warning that names the replacement. Ship the marker in a minor release, list it under “Deprecated” in the changelog, and remove the function only in a later major release. Deprecation is a notice period: nothing breaks on the day you announce it, and everyone has time to move.
| Language | How you mark it | What callers see |
|---|---|---|
| Python 3.13+ | @warnings.deprecated("Use g") | Runtime warning and a type-checker diagnostic |
| Python, any version | warnings.warn(msg, DeprecationWarning, stacklevel=2) | Runtime warning, hidden by default outside __main__ |
| JavaScript / TypeScript | /** @deprecated Use g */ | Strikethrough in editors such as VS Code |
| Node.js | util.deprecate(fn, msg, code) | One warning on stderr, on the first call |
| npm package | npm deprecate pkg@"<2" "msg" | A warning when anyone installs that version |
| Java | @Deprecated(since = "2.3", forRemoval = true) | Compiler warning |
| Go | A // Deprecated: use G paragraph in the doc comment | Warnings from tools that read it |
| Rust | #[deprecated(since = "2.3.0", note = "use g")] | rustc warning |
| C# | [Obsolete("Use G")] | Warning CS0618, or error CS0619 if set to error |
What does it mean to deprecate a function?
It means telling callers to stop using a function, usually because it is going away, while it still works exactly as before. A deprecated function returns the same results, and the only change is a warning pointing to what replaces it, plus a version or date after which it may be removed.
Java’s documentation lists the usual reasons: the element’s “usage is likely to lead to errors; it may be changed incompatibly or removed in a future version; it has been superseded by a newer, usually preferable alternative; or it is obsolete.” Removing a function without that warning period is a breaking change with no notice, which is what deprecation exists to prevent. For services rather than libraries, API deprecation covers the same idea with response headers and sunset dates.
How do you deprecate a function in Python?
On Python 3.13 or later, decorate it with warnings.deprecated and a message. On older versions, call warnings.warn with DeprecationWarning and stacklevel=2 at the top of the function. Both keep the function working and point the warning at the caller’s line.
from warnings import deprecated
@deprecated("Use load_config() instead; removed in 3.0")
def read_config(path):
return load_config(path)
The warnings documentation says that with the decorator, “static type checkers will also generate a diagnostic on usage of the deprecated object,” and at runtime the warning is emitted on calls, or for a class on instantiation and on subclassing. The decorator was added in 3.13 by PEP 702. The older form works everywhere:
import warnings
def read_config(path):
warnings.warn(
"read_config() is deprecated; use load_config()",
DeprecationWarning,
stacklevel=2,
)
return load_config(path)
The stacklevel=2 matters. Without it, the warning reports the line inside your library, which tells the caller nothing. With it, the docs explain, the warning refers to the caller “rather than to the source of” the deprecated function itself.
Expect most users to miss the warning. DeprecationWarning is “ignored by default, unless triggered by code in __main__,” so calls from inside another package stay silent. The same page tells developers to test “with typically ignored warnings made visible.” Running a test suite with python -W error::DeprecationWarning turns each warning into a failure nobody can miss, which is worth suggesting to callers in the release notes.
How do you deprecate a function in JavaScript and TypeScript?
Add a @deprecated tag to the function’s JSDoc comment, with a short note naming the replacement. Editors pick it up and strike the name through wherever it is used. For a runtime warning in Node.js, wrap the function in util.deprecate.
/**
* @deprecated Since 2.4. Use loadConfig() instead.
*/
export function readConfig(path) {
return loadConfig(path);
}
JSDoc defines the tag as marking “a symbol in your code as being deprecated.” Since TypeScript 4.0, the language service surfaces it “in completion lists and as a suggestion diagnostic,” which VS Code shows as strikethrough text.
Node’s util.deprecate returns a wrapped function that emits a DeprecationWarning and prints it to stderr “the first time the returned function is called,” then stays quiet. A deprecation code such as 'DEP_MYLIB_001' makes the warning fire once per code, and users can turn warnings into exceptions with --throw-deprecation.
To deprecate a whole package version rather than one function, npm deprecate updates the registry entry, “providing a deprecation warning to all who attempt to install it.” It accepts ranges, and an empty message removes the deprecation.
How do Java, Go, Rust and C# mark deprecated code?
Each has a built-in marker that the compiler or its tools read. Java uses an annotation, C# and Rust use attributes, and Go uses a comment convention.
Java. Pair the @Deprecated annotation with the @deprecated Javadoc tag. Since Java 9 the annotation takes since and forRemoval; per the API documentation, forRemoval = true “indicates intent to remove the annotated program element in a future version.” Compilers warn “when a deprecated program element is used or overridden in non-deprecated code.”
Go. Add a paragraph that starts with Deprecated: to the doc comment. The Go wiki notes that “some tools will warn on use of deprecated identifiers.” A whole module can be deprecated the same way in a comment on the module line of go.mod, and since Go 1.17 go list -m -u and go get check for deprecated modules, according to the modules reference.
Rust. Use #[deprecated(since = "2.3.0", note = "use bar")]. The Rust reference says rustc “will issue warnings on use of #[deprecated] items,” and rustdoc shows the since version and note.
C#. Use [Obsolete("Use NewMethod instead")]. The .NET documentation shows that a call to such a member compiles with warning CS0618, while [Obsolete("...", true)] makes it error CS0619. The error form fails every caller’s build, which makes it a breaking change, so ship it only in a major release, if you use it at all.
Which release should a deprecation ship in?
A minor release, with removal in a later major release. Marking a function deprecated adds information without breaking anything, so a minor version is enough; removing the function breaks callers, so that waits for a major version.
The Semantic Versioning specification makes the first half a rule: the minor version “MUST be incremented if any public API functionality is marked as deprecated.” Its FAQ adds the second: “Before you completely remove the functionality in a new major release there should be at least one minor release that contains the deprecation so that users can smoothly transition to the new API.” How each bump maps to a changelog section is covered in semantic versioning and your changelog.
What should a deprecation message say?
Three things: what to use instead, when the old function will go, and where to read more. A warning that only says “deprecated” sends every caller off to search for the answer you already know.
Java’s documentation asks for the reason in the @deprecated tag and says it “should also suggest and link to a recommended replacement API.” It adds a warning worth repeating: “A replacement API often has subtly different semantics, so such issues should be discussed as well.” If load_config() raises where read_config() returned None, say so in the message or the linked guide.
A useful pattern for the text: read_config() is deprecated since 2.4 and will be removed in 3.0; use load_config(), which raises FileNotFoundError instead of returning None. See the 3.0 migration guide.
How do you record a deprecation in the changelog?
Add an entry under a “Deprecated” heading in the release that adds the warning, and a matching entry under “Removed” in the release that deletes the function. The changelog reaches readers who never see the warning, such as anyone reading ahead of a major upgrade.
Keep a Changelog defines both types: “Deprecated for soon-to-be removed features” and “Removed for now removed features.” Its advice is blunt: “If you do nothing else, list deprecations, removals, and any breaking changes in your changelog.”
## [2.4.0] - 2026-10-31
### Deprecated
- `read_config()`: use `load_config()`. Removal in 3.0.
## [3.0.0] - 2027-03-02
### Removed
- `read_config()`, deprecated since 2.4.0.
The structure of the rest of the file is covered in Keep a Changelog explained. Changeloop sends each merged pull request to a review inbox, as the docs describe, where it waits as a draft unless auto-publish is on for that repository. A pull request that only adds a deprecation marker leaves the function’s results unchanged, so it may arrive marked as an internal change and discarded; restore it there and write the Deprecated entry yourself. For a quick one-off, the changelog generator turns a list of commits into a draft entry.
FAQ
What is the difference between deprecated and obsolete?
Deprecated means a function or other API still works but callers should move away from it, usually because it will be removed. Go’s standard library keeps deprecated identifiers for compatibility, and a Java @Deprecated with forRemoval = false carries no removal plan. Obsolete is often used as a synonym, and C# names its marker Obsolete, but in everyday use it describes something already replaced or no longer useful.
Does deprecating a function break anything?
No, a deprecated function keeps working and only produces a warning. The exceptions are setups that turn warnings into failures, such as Python’s -W error or Node’s --throw-deprecation, where the caller’s own tests or build stop on the warning. A C# Obsolete marker set to error fails every caller’s build, so treat that form as a breaking change.
Can you undo a deprecation?
Yes. Remove the marker in a later release and say so in the changelog. For npm packages, running npm deprecate with an empty message removes the deprecation, and Go lets a module author change or remove the deprecation message in a later version.
How long should a deprecated function stay in the code? At least one minor release before the major release that removes it, which is the Semantic Versioning minimum. Keeping it longer helps users who upgrade rarely, and saying the planned removal version in the warning lets callers plan for it.
The technical claims in this article have not been independently reviewed. If something here is wrong, tell us and we will correct it.