Skip to content
Tutorials Center
My learning

Topics

Python Reference ยท Exceptions

The warnings module

Reference for the Python warnings module: warn(), warning categories, filters, catch_warnings(), turning warnings into errors and deprecating your own APIs.

The warnings module reports problems that deserve attention but should not stop the program: a function that is going away, a risky default, a suspicious value. A warning is printed to standard error (by default once per location), and the program carries on. Filters decide whether each warning is shown, ignored or turned into an exception.

Every warning has a category, a class that derives from Warning. The ones you will meet most are UserWarning (the default), DeprecationWarning (a feature will be removed), FutureWarning (behavior will change for end users), SyntaxWarning, RuntimeWarning and ResourceWarning.

Python
import warnings
warnings.warn("old_function() is deprecated", DeprecationWarning, stacklevel=2)

Try it

Python Recording warnings

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 input()), it gets the next line from this box.

Python Filters, errors and deprecating your own 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 input()), it gets the next line from this box.

Syntax

Python
warnings.warn(message, category=UserWarning, stacklevel=1)
warnings.simplefilter(action, category=Warning)
warnings.filterwarnings(action, message="", category=Warning, module="", lineno=0)

with warnings.catch_warnings(record=True) as caught:
    ...
Name Description
message The text, or a Warning instance (then category is ignored).
category A Warning subclass; defaults to UserWarning.
stacklevel How many frames up to blame. Use 2 in a library function so the warning points at the caller.
action "default", "error", "ignore", "always", "module" or "once".
record With catch_warnings(record=True): collect WarningMessage objects in a list instead of printing.

Return value: warn() returns None. With action="error" the warning is raised as an exception of its category.

Usage notes

  • Default visibility. By default DeprecationWarning is shown only when triggered by code in __main__, and PendingDeprecationWarning and ImportWarning are hidden. Test runners such as pytest enable them. Use python -W default or -W error to see more.
  • catch_warnings() saves and restores the filters, so changes inside the with block do not leak. It is not thread-safe, and it is best used in tests and short blocks.
  • Duplicate suppression. Under the "default" action each unique message and location is shown once; "always" shows every one, and "once" shows the first occurrence for the whole program.
  • Choose the right category. DeprecationWarning is aimed at developers, FutureWarning at users of the application; RuntimeWarning is for dubious runtime behavior.
  • Warnings versus exceptions. Raise an exception when the operation cannot succeed; warn when it can proceed but the caller should know.
  • Warnings versus logging. logging.captureWarnings(True) routes warnings into the logging system; plain logging is better for events inside your application.
  • Deprecation decorator. Python 3.13 added warnings.deprecated (a decorator) to mark functions and classes, and type checkers understand it.
  • Command line and environment. -W error::DeprecationWarning and the PYTHONWARNINGS variable set filters without editing code.
  • Do not hide everything. A global simplefilter("ignore") silences real problems. Filter by category and module instead.