Text of peps.python.org › pep-0565 as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 565 – Show DeprecationWarning in __main__ | peps.python.org

PEP 565 – Show DeprecationWarning in __main__ PEP 565 – Show DeprecationWarning in __main__ Author : Alyssa Coghlan <ncoghlan at gmail.com> Status : Final Type : Standards Track Created : 12-Nov-2017 Python-Version : 3.7 Post-History : 12-Nov-2017, 25-Nov-2017 Resolution : Python-Dev message Table of Contents Abstract Specification New default warnings filter entry Additional use case for FutureWarning Recommended filter settings for test runners Recommended filter settings for interactive shells Other documentation updates Reference Implementation Motivation Limitations on PEP Scope References Copyright Abstract In Python 2.7 and Python 3.2, the default warning filters were updated to hide DeprecationWarning by default, such that deprecation warnings in development tools that were themselves written in Python (e.g. linters, static analysers, test runners, code generators), as well as any other applications that merely happened to be written in Python, wouldn’t be visible to their users unless those users explicitly opted in to seeing them.

However, this change has had the unfortunate side effect of making DeprecationWarning markedly less effective at its primary intended purpose: providing advance notice of breaking changes in APIs (whether in CPython, the standard library, or in third party libraries) to users of those APIs. To improve this situation, this PEP proposes a single adjustment to the default warnings filter: displaying deprecation warnings attributed to the main module by default.

This change will mean that code entered at the interactive prompt and code in single file scripts will revert to reporting these warnings by default, while they will continue to be silenced by default for packaged code distributed as part of an importable module. The PEP also proposes a number of small adjustments to the reference interpreter and standard library documentation to help make the warnings subsystem more approachable for new Python developers.

As part of the documentation updates, it will be made clearer that the unittest test runner displays all warnings by default when executing test cases, and that other test runners are advised to follow that example. Specification New default warnings filter entry The current set of default warnings filters consists of: ignore :: DeprecationWarning ignore :: PendingDeprecationWarning ignore :: ImportWarning ignore :: BytesWarning ignore :: ResourceWarning The default unittest test runner then uses warnings.catch_warnings() warnings.simplefilter('default') to override the default filters while running test cases.

The change proposed in this PEP is to update the default warning filter list to be: default :: DeprecationWarning : __main__ ignore :: DeprecationWarning ignore :: PendingDeprecationWarning ignore :: ImportWarning ignore :: BytesWarning ignore :: ResourceWarning This means that in cases where the nominal location of the warning (as determined by the stacklevel parameter to warnings.warn ) is in the __main__ module, the first occurrence of each DeprecationWarning will once again be reported.

This change will lead to DeprecationWarning being displayed by default for: code executed directly at the interactive prompt code executed directly as part of a single-file script While continuing to be hidden by default for: code imported from another module in a zipapp archive’s __main__.py file code imported from another module in an executable package’s __main__ submodule code imported from an executable script wrapper generated at installation time based on a console_scripts or gui_scripts entry point definition This means that tool developers that create an installable or executable artifact (such as a zipapp archive) for distribution to their users shouldn’t see any change from the status quo, while users of more ad hoc personal or locally distributed scripts are likely to start seeing relevant deprecation warnings again (as they did in Python 2.6 and earlier).

Additional use case for FutureWarning The standard library documentation will be updated to explicitly recommend the use of FutureWarning (rather than DeprecationWarning ) for backwards compatibility warnings that are intended to be seen by users of an application. (This will be in addition to the existing use of FutureWarning to warn about constructs that will remain valid code in the future, but will have different semantics).

This will give the following three distinct categories of backwards compatibility warning, with three different intended audiences: PendingDeprecationWarning : hidden by default for all code. The intended audience is Python developers that take an active interest in ensuring the future compatibility of their software (e.g. professional Python application developers with specific support obligations). DeprecationWarning : reported by default for code that runs directly in the __main__ module (as such code is considered relatively unlikely to have a dedicated test suite), but hidden by default for code in other modules.

The intended audience is Python developers that are at risk of upgrades to their dependencies (including upgrades to Python itself) breaking their software (e.g. developers using Python to script environments where someone else is in control of the timing of dependency upgrades). FutureWarning : reported by default for all code. The intended audience is users of applications written in Python, rather than other Python developers (e.g. warning about use of a deprecated setting in a configuration file format).

For library and framework authors that want to ensure their API compatibility warnings are more reliably seen by their users, the recommendation is to use a custom warning class that derives from DeprecationWarning in Python 3.7+, and from FutureWarning in earlier versions. Recommended filter settings for test runners Developers of test runners are advised to implement logic equivalent to the following when determining their default warnings filters: if not sys . warnoptions : warnings . simplefilter ( "default" ) This effectively enables all warnings by default, as if the -Wd command line option had been passed.

Note that actually enabling BytesWarning in a test suite still requires passing the -b option to the interpreter at the command line. For implicit bytes conversion and bytes comparison warnings, the warnings filter machinery is only used to determine whether they should be printed as warnings or raised as exceptions - when the command line flag isn’t set, the interpreter doesn’t even emit the warning in the first place.

Recommended filter settings for interactive shells Developers of interactive shells are advised to add a filter that enables DeprecationWarning in the namespace where user code is entered and executed. If that namespace is __main__ (as it is for the default CPython REPL), then no changes are needed beyond those in this PEP. Interactive shell implementations which use a namespace other than __main__ will need to add their own filter.

For example, IPython uses the following command ( [6] ) to set up a suitable filter: warnings . filterwarnings ( "default" , category = DeprecationWarning , module = self . user_ns . get ( "__name__" )) Other documentation updates The current reference documentation for the warnings system is relatively short on specific examples of possible settings for the -W command line option or the PYTHONWARNINGS environment variably that achieve particular end results.

The following improvements are proposed as part of the implementation of this PEP: Explicitly list the following entries under the description of the PYTHONWARNINGS environment variable: PYTHONWARNINGS = error # Convert to exceptions PYTHONWARNINGS = always # Warn every time PYTHONWARNINGS = default # Warn once per call location PYTHONWARNINGS = module # Warn once per calling module PYTHONWARNINGS = once # Warn once per Python process PYTHONWARNINGS = ignore # Never warn Explicitly l

The rest of this page is on the live site.