The warnings Module
The warnings module lets your code raise non-fatal alerts — like deprecation notices — that surface a message to the caller without stopping the program.
Learn The warnings Module in our free Python course — an interactive lesson with runnable examples, a practice exercise and a quick reference.
Part of the free Python course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.
It's how libraries say "this still works, but you should change it." You'll learn to emit warnings, choose categories, filter them, and even turn them into errors when you need to.
warnings.warn(message, category) raises a warning and keeps running. To make the demos here produce deterministic output, we capture warnings with catch_warnings(record=True) instead of letting them print to stderr:
Filters decide what happens to each warning. simplefilter(action) applies one action to everything; filterwarnings(action, category=...) targets a specific category. Actions include "always" , "once" , "ignore" , and "error" :
Filters are checked in order, most-recently-added first. Inside a catch_warnings block your changes are temporary — the original filter state is restored when the block exits, so you never leak settings into the rest of the program.
The "error" action promotes a warning to a real exception, which you can then catch with try/except . This is invaluable in tests and CI: it makes a deprecated code path fail loudly instead of slipping by unnoticed:
Fill in each ___ so the code emits a warning and captures it for inspection. (Hint: the function to emit is warn , and the context manager records with record=True .)
❌ Wondering why a DeprecationWarning "didn't fire"
✅ It's hidden by default — enable it explicitly to see it
❌ Expecting catch_warnings to record without record=True
✅ Raise an exception when continuing is wrong
Two functions emit warnings. Capture all of them, then count how many are DeprecationWarning s versus other categories — exactly the kind of audit you'd run before a release.
Lesson complete — you signal problems gracefully!
You can emit warnings with warnings.warn , choose categories like UserWarning and DeprecationWarning , capture them with catch_warnings(record=True) , filter with simplefilter and filterwarnings , and promote them to errors when you want failures to be loud.
🚀 Up next: introspection with inspect — examine functions, signatures, and source at runtime.
Practice quiz
How does a warning differ from an exception?
- A warning always crashes the program; an exception does not
- A warning surfaces a message but the program keeps running; an exception interrupts flow
- They are identical in behavior
- A warning can only be raised inside a try block
Answer: A warning surfaces a message but the program keeps running; an exception interrupts flow. A warning is advisory and execution continues; an exception interrupts the flow and must be caught or the program crashes.
What function emits a warning?
- warnings.raise(...)
- warnings.warn(message, category)
- warnings.alert(...)
- warnings.emit(...)
Answer: warnings.warn(message, category). warnings.warn(message, category) raises a warning and keeps running.
What is the default category for a bare call like warnings.warn('msg')?
- DeprecationWarning
- RuntimeWarning
- UserWarning
- FutureWarning
Answer: UserWarning. A bare warnings.warn defaults to UserWarning, which is shown by default.
Why might a DeprecationWarning appear to 'not fire' in a normal program run?
- DeprecationWarning is hidden by default so end users aren't spammed
- DeprecationWarning does not exist
- It only works in Python 2
- It requires an internet connection
Answer: DeprecationWarning is hidden by default so end users aren't spammed. DeprecationWarning is hidden by default in normal runs, but shown under tests or with -W flags.
To capture warnings into a list for inspection, what must you pass to catch_warnings?
- record=True
- capture=True
- save=True
- list=True
Answer: record=True. with warnings.catch_warnings(record=True) as caught: gives you a list of recorded warnings; without record=True the value is None.
Which filter action turns a matching warning into a real exception?
- 'always'
- 'once'
- 'ignore'
- 'error'
Answer: 'error'. The 'error' action promotes the warning to an exception you can catch with try/except — useful in tests and CI.
What does filterwarnings('ignore', category=DeprecationWarning) do?
- Promotes DeprecationWarnings to errors
- Silences only DeprecationWarnings while leaving other categories alone
- Silences every warning
- Records all warnings to a file
Answer: Silences only DeprecationWarnings while leaving other categories alone. filterwarnings targets one category; 'ignore' on DeprecationWarning drops just those, keeping e.g. UserWarnings.
Why scope simplefilter('error') inside a catch_warnings block?
- Because it runs faster there
- So the filter change is temporary and the original state is restored on exit
- Because simplefilter only works inside that block
- To capture the warning to disk
Answer: So the filter change is temporary and the original state is restored on exit. Inside catch_warnings the filter state is restored when the block exits, so you don't leak 'error' settings into unrelated code.
After a warning is promoted with the 'error' action, how do you handle it?
- With warnings.handle()
- It cannot be handled
- Catch it with try/except, because it is now a real exception
- Call warnings.resetwarnings()
Answer: Catch it with try/except, because it is now a real exception. A promoted warning IS an exception, so you catch it like any other: try: warnings.warn(...) except SomeWarning: ...
When should you raise an exception instead of emitting a warning?
- When the situation is recoverable and the caller can keep going
- When continuing would be wrong or impossible, like a missing required config file
- Whenever a deprecated function is called
- Never — always warn
Answer: When continuing would be wrong or impossible, like a missing required config file. Warn when recoverable; raise when continuing is wrong or impossible (e.g. FileNotFoundError for a missing config) so it fails fast.