Warnings & Deprecations

The warnings module signals recoverable issues and API deprecations without raising exceptions. Configure filters to show, ignore, or escalate warnings - libraries use DeprecationWarning for scheduled removals.

Recipe

import warnings
 
warnings.warn("old_api is deprecated; use new_api", DeprecationWarning, stacklevel=2)

When to reach for this:

• Deprecating functions/classes before removal
• Runtime notices about suboptimal usage (not errors)
• Library maintainers warn without breaking callers immediately
• CI -W error turns warnings into test failures
• Distinguish user code (UserWarning) from internal (DeprecationWarning)

Working Example

import warnings
 
warnings.simplefilter("default", DeprecationWarning)
 
def old_price(amount: float) -> float:
    warnings.warn(
        "old_price deprecated; use compute_price",
        DeprecationWarning,
        stacklevel=2,
    )
    return amount * 1.1
 
def compute_price(amount: float) -> float:
    return amount * 1.1
 
warnings.filterwarnings("once", category=UserWarning, module=__name__)
 
def maybe_risky(flag: bool) -> None:
    if flag:
        warnings.warn("experimental path enabled", UserWarning, stacklevel=2)
 
old_price(10)
maybe_risky(True)
maybe_risky(True)  # once filter suppresses duplicate

What this demonstrates:

• stacklevel=2 points warning at caller, not wrapper
• DeprecationWarning category for API sunset
• filterwarnings("once") avoids log spam
• Filters scoped by category and module

Deep Dive

How It Works

• warnings.warn(message, category, stacklevel) emits WarningMessage
• Default: show each warning once per location to stderr
• warnings.filterwarnings(action, category, ...) controls behavior
• pytest.warns asserts warnings in tests
• @warnings.deprecated decorator (3.13+) for functions

Common Categories

Gotchas

• Wrong stacklevel - warning blames library line. Fix: increment stacklevel for each wrapper layer.
• DeprecationWarning invisible in REPL - default filters hide from non-main. Fix: document warnings.simplefilter for app entry or run tests with -W default::DeprecationWarning.
• Using warnings for control flow - not exceptions, easy to miss. Fix: warnings for deprecations only, not business logic.
• Breaking CI without policy - -W error fails on any warning. Fix: treat deprecations as errors, allowlist third-party noise temporarily.
• No removal timeline in message - users cannot plan. Fix: include version removal target in warn text.

Alternatives

FAQs

Related

• The logging Module - captureWarnings integration
• Custom Exception Hierarchies - hard breaks vs soft warns
• Errors & Logging Best Practices - deprecation policy
• Raising & Chaining - when to raise instead

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.