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.
import warnings warnings.warn("old_function() is deprecated", DeprecationWarning, stacklevel=2)
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 input()), 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 input()), it gets the next line from this box.
Syntax
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
DeprecationWarningis shown only when triggered by code in__main__, andPendingDeprecationWarningandImportWarningare hidden. Test runners such as pytest enable them. Usepython -W defaultor-W errorto see more. catch_warnings()saves and restores the filters, so changes inside thewithblock 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.
DeprecationWarningis aimed at developers,FutureWarningat users of the application;RuntimeWarningis 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; plainloggingis 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::DeprecationWarningand thePYTHONWARNINGSvariable set filters without editing code. - Do not hide everything. A global
simplefilter("ignore")silences real problems. Filter by category and module instead.