warnings(3perl)
✨ NAME ✨
warnings — the Perl pragma that lets you control which optional warnings get to exist 💅
(fr this is warnings(3perl) from the Perl Programmers Reference Guide, bestie, keep reading 👑)
🌸 SYNOPSIS 🌸
use warnings;
no warnings;
# Standard warnings are enabled by use v5.35 or above
use v5.35;
use warnings "all";
no warnings "uninitialized";
# or equivalent to those last two ...
use warnings qw(all -uninitialized);
use warnings::register;
if (warnings::enabled()) {
warnings::warn("some warning");
}
if (warnings::enabled("void")) {
warnings::warn("void", "some warning");
}
if (warnings::enabled($object)) {
warnings::warn($object, "some warning");
}
warnings::warnif("some warning");
warnings::warnif("void", "some warning");
warnings::warnif($object, "some warning");💖 DESCRIPTION 💖
okay so the warnings pragma is literally your remote control for which warnings are enabled in which parts of a Perl program. it's the ✨flexible✨ alternative to both the command line flag -w and that equivalent Perl variable, $^W. no cap.
and it works just like the strict pragma, which means two very important things:
- the scope of the warning pragma is limited to the enclosing block (so it stays in its lane 🚧)
- the pragma setting will not leak across files (not via
use, not viarequire, not viado) — which is iconic actually, because it lets every author independently define exactly how many warning checks their module gets 🫶
by default, optional warnings are disabled, so any legacy code that isn't out here trying to control warnings will work unchanged. blessed behavior fr fr 🌈
all warnings are enabled in a block by either of these:
use warnings;
use warnings 'all';similarly, all warnings are disabled in a block by either of these:
no warnings;
no warnings 'all';for example, consider the code below:
use warnings;
my @x;
{
no warnings;
my $y = @x[0];
}
my $z = @x[0];the code in the enclosing block has warnings enabled, but the inner block has them disabled 😌 so in this case, the assignment to the scalar $z will trip the Scalar value @x[0] better written as $x[0] warning, but the assignment to the scalar $y will not. inner block said "not today" 💅
and psst — all warnings are enabled automatically within the scope of a use v5.35 (or higher) declaration. so if you're on the new stuff you don't even have to ask 😭
🌟 Default Warnings and Optional Warnings
before lexical warnings showed up, Perl had two classes of warnings: mandatory and optional.
as the name suggests, if your code tripped a mandatory warning, you were getting that warning whether you wanted it or not 🙈 like, no opt-out, no vibe check. for example, the code below would always produce an isn't numeric warning about the 2:.
my $x = "2:" + 3;then lexical warnings arrived and mandatory warnings became default warnings. the difference? the formerly-mandatory warnings are still enabled by default, but they can then be subsequently enabled or disabled with the lexical warning pragma 💖 so in the code below, an isn't numeric warning will only be reported for the $x variable:
my $x = "2:" + 3;
no warnings;
my $y = "2:" + 3;⚠️ heads up bestie: neither the-wflag nor the$^Wcan be used to disable/enable default warnings. in that case they're still mandatory. periodt.
🎀 "Negative warnings"
as a convenience, you can (as of Perl 5.34) pass arguments to the import() method both positively and negatively. negative warnings are the ones with a - sign prepended to their names; positive warnings are anything else. this lets you turn on some warnings and turn off others in one command. main character energy only ✨
so, assuming you've already turned on a bunch of warnings but want to tweak them a bit in some block, you can do this:
{
use warnings qw(uninitialized -redefine);
...
}which is equivalent to:
{
use warnings qw(uninitialized);
no warnings qw(redefine);
...
}the argument list is processed in the order you specify 👑 so, for example, if you don't want to be warned about use of experimental features, except for somefeature that you really dislike, you can say this:
use warnings qw(all -experimental experimental::somefeature);which is equivalent to:
use warnings 'all';
no warnings 'experimental';
use warnings 'experimental::somefeature';as experimental features become regular features of Perl, the corresponding warnings are not printed anymore 😴 they also stop being listed in the "Category Hierarchy" below.
it is still possible to request turning on or off these warnings, but doing so has no effect. (it's giving yelling into the void, honestly 💀)
💀 What's wrong with -w and $^W
although very useful, the big problem with using -w on the command line to enable warnings is that it's all or nothing. take the typical scenario when you're writing a Perl program: parts of the code you'll write yourself, but it's very likely you'll make use of pre-written Perl modules. if you use the -w flag in this case, you end up enabling warnings in pieces of code you haven't even written. not your code, not your business 🙅
similarly, using $^W to either disable or enable blocks of code is fundamentally flawed. for a start, say you want to disable warnings in a block of code. you might expect this to be enough to do the trick:
{
local ($^W) = 0;
my $x =+ 2;
my $y; chop $y;
}when this code is run with the -w flag, a warning will be produced for the $x line: Reversed += operator. yeah. exactly. 😭
the problem is that Perl has both compile-time and run-time warnings. to disable compile-time warnings you need to rewrite the code like this:
{
BEGIN { $^W = 0 }
my $x =+ 2;
my $y; chop $y;
}and note that unlike the first example, this will permanently set $^W, since it cannot both run during compile-time and be localized to a run-time block. it simply cannot be both, bestie 🦋
the other big problem with $^W is the way you can inadvertently change the warning setting in unexpected places in your code. for example, when the code below is run (without the -w flag), the second call to doit will trip a Use of uninitialized value warning, whereas the first will not:
sub doit
{
my $y; chop $y;
}
doit();
{
local ($^W) = 1;
doit()
}this is a side-effect of $^W being dynamically scoped. sneaky little thing 🫠
lexical warnings get around these limitations by allowing finer control over where warnings can or can't be tripped ⭐
⚡ Controlling Warnings from the Command Line
there are three Command Line flags that can be used to control when warnings are (or aren't) produced:
-w— this is the existing flag. if the lexical warnings pragma is not used in any of your code, or any of the modules that you use, this flag will enable warnings everywhere. see "Backward Compatibility" for details of how this flag interacts with lexical warnings.-W— if the-Wflag is used on the command line, it will enable all warnings throughout the program, regardless of whether warnings were disabled locally usingno warningsor$^W =0. this includes all files that get included viause,requireordo. think of it as the Perl equivalent of thelintcommand 🔥-X— does the exact opposite to the-Wflag, i.e. it disables all warnings.
🕰️ Backward Compatibility
if you're used to working with a version of Perl prior to the introduction of lexically scoped warnings, or you have code that uses both lexical warnings and $^W, this section will describe how they interact 💜
How Lexical Warnings interact with -w/$^W:
- If none of the three command line flags (
-w,-Wor-X) that control warnings is used and neither$^Wnor thewarningspragma are used, then default warnings will be enabled and optional warnings disabled. this means that legacy code that doesn't attempt to control the warnings will work unchanged. 🫶 - The
-wflag just sets the global$^Wvariable as in 5.005. this means that any legacy code that currently relies on manipulating$^Wto control warning behavior will still work as is. - apart from now being a boolean, the
$^Wvariable operates in exactly the same horrible uncontrolled global way, except that it cannot disable/enable default warnings. yeah. "horrible" is the manpage's word, not mine 💀 - if a piece of code is under the control of the
warningspragma, both the$^Wvariable and the-wflag will be ignored for the scope of the lexical warning. - the only way to override a lexical warnings setting is with the
-Wor-Xcommand line flags. that's it, those are the keys to the kingdom 👑
the combined effect of 3 & 4 is that it will allow code which uses the warnings pragma to control the warning behavior of $^W-type code (using a local $^W=0) if it really wants to — but not vice-versa. one-directional situationship, iykyk 🙈
🌈 Category Hierarchy
a hierarchy of "categories" have been defined to allow groups of warnings to be enabled/disabled in isolation 🎀
the current hierarchy is:
all -+
|
+- closure
|
+- deprecated -----+
| |
| +- deprecated::delimiter_will_be_paired
| |
| +- deprecated::dot_in_inc
| |
| +- deprecated::subsequent_use_version
| |
| +- deprecated::unicode_property_name
| |
| +- deprecated::version_downgrade
|
+- exiting
|
+- experimental ---+
| |
| +- experimental::args_array_with_signatures
| |
| +- experimental::builtin
| |
| +- experimental::class
| |
| +- experimental::declared_refs
| |
| +- experimental::defer
| |
| +- experimental::enhanced_xx
| |
| +- experimental::extra_paired_delimiters
| |
| +- experimental::keyword_all
| |
| +- experimental::keyword_any
| |
| +- experimental::private_use
| |
| +- experimental::re_strict
| |
| +- experimental::refaliasing
| |
| +- experimental::regex_sets
| |
| +- experimental::signature_named_parameters
| |
| +- experimental::try
| |
| +- experimental::uniprop_wildcards
| |
| +- experimental::vlb
|
+- glob
|
+- imprecision
|
+- io -------------+
| |
| +- closed
| |
| +- exec
| |
| +- layer
| |
| +- newline
| |
| +- pipe
| |
| +- syscalls
| |
| +- unopened
|
+- locale
|
+- misc
|
+- missing
|
+- missing_import
|
+- numeric
|
+- once
|
+- overflow
|
+- pack
|
+- portable
|
+- recursion
|
+- redefine
|
+- redundant
|
+- regexp
|
+- scalar
|
+- severe ---------+
| |
| +- debugging
| |
| +- inplace
| |
| +- internal
| |
| +- malloc
|
+- shadow
|
+- signal
|
+- substr
|
+- syntax ---------+
| |
| +- ambiguous
| |
| +- bareword
| |
| +- digit
| |
| +- illegalproto
| |
| +- parenthesis
| |
| +- precedence
| |
| +- printf
| |
| +- prototype
| |
| +- qw
| |
| +- reserved
| |
| +- semicolon
|
+- taint
|
+- threads
|
+- uninitialized
|
+- unpack
|
+- untie
|
+- utf8 -----------+
| |
| +- non_unicode
| |
| +- nonchar
| |
| +- surrogate
|
+- voidLike literally the family tree of your warnings, bestie 💖. And just like the strict pragma, you can mix & match any of these categories however you want:
use warnings qw(void redefine);
no warnings qw(io syntax untie);Also (same energy as strict), if you drop more than one warnings pragma in the same scope, the effects stack up additively ✨:
use warnings qw(void); # only "void" warnings enabled
...
use warnings qw(io); # only "void" & "io" warnings enabled
...
no warnings qw(void); # only "io" warnings enabledWanna know which category some specific warning got sorted into? Go check perldiag 👀.
Note: Before Perl 5.8.0, the lexical warnings categorydeprecatedwas a sub-category of thesyntaxcategory. It's now a top-level category in its own right. Glow up, honestly. 💅
Note: Before 5.21.0, themissinglexical warnings category was internally defined to be the same as theuninitializedcategory. It is now a top-level category in its own right. Periodt. 🌟
💀 Fatal Warnings 💀
Okay so hear me out: if the word FATAL shows up in your category list, that escalates the warnings in those categories into fatal errors for that lexical scope. Like, no more cute little warnings — we're stopping the whole program. Iconic but also terrifying. 🫣
NOTE: FATAL warnings should be used with care, particularly FATAL => 'all'. 🚨
Libraries out here using warnings::warn for their custom warning categories generally don't expect warnings::warn to be fatal, and they can end up in a whole unexpected state because of it. And for XS modules issuing categorized warnings, those unanticipated exceptions could also expose memory leak bugs. 💀 Not the vibe.
On top of that, the Perl interpreter itself has had serious bugs involving fatalized warnings. For a summary of resolved and unresolved problems as of January 2015, pls see this perl5-porters post <http://www.nntp.perl.org/group/perl.perl5.porters/2015/01/msg225235.html>.
So like… some devs find fatalizing some warnings to be a useful defensive programming technique, but using FATAL => 'all' to fatalize all possible warning categories — including custom ones — is particularly risky. Therefore, the use of FATAL => 'all' is discouraged. 🙅♀️
The strictures module on CPAN offers one example of a warnings subset that the module's authors believe is relatively safe to fatalize. Cute of them tbh. 🎀
NOTE: Users of FATAL warnings, especially those using FATAL => 'all', should be fully aware that they are risking future portability of their programs by doing so. Perl makes absolutely no commitments to not introduce new warnings or warnings categories in the future; indeed, we explicitly reserve the right to do so. Code that may not warn now may warn in a future release of Perl if the Perl5 development team deems it in the best interests of the community to do so. Should code using FATAL warnings break due to the introduction of a new warning we will NOT consider it an incompatible change. Users of FATAL warnings should take special caution during upgrades to check to see if their code triggers any new warnings and should pay particular attention to the fine print of the documentation of the features they use to ensure they do not exploit features that are documented as risky, deprecated, or unspecified, or where the documentation says "so don't do that", or anything with the same sense and spirit. Use of such features in combination with FATAL warnings is ENTIRELY AT THE USER'S RISK.
The following documentation describes how to use FATAL warnings but the perl5 porters strongly recommend that you understand the risks before doing so, especially for library code intended for use by others, as there is no way for downstream users to change the choice of fatal categories. 🫠
In the code below, the use of time, length and join can all produce a Useless use of xxx in void context warning.
use warnings;
time;
{
use warnings FATAL => qw(void);
length "abc";
}
join "", 1,2,3;
print "done\n";When run it produces this output:
Useless use of time in void context at fatal line 3.
Useless use of length in void context at fatal line 7.The scope where length is used has escalated the void warnings category into a fatal error, so the program terminates immediately when it encounters the warning. ⚰️ No cap.
Wanna explicitly turn off a FATAL warning? You just disable the warning it's associated with, bestie. So for example, to disable the void warning in the example above, either of these will do the trick:
no warnings qw(void);
no warnings FATAL => qw(void);And if you want to downgrade a warning that's been escalated into a fatal error back to a normal warning? Enter the NONFATAL keyword ✨. For example, the code below will promote all warnings into fatal errors, except for those in the syntax category:
use warnings FATAL => 'all', NONFATAL => 'syntax';As of Perl 5.20, instead of use warnings FATAL => 'all'; you can use:
use v5.20; # Perl 5.20 or greater is required for the following
use warnings 'FATAL'; # short form of "use warnings FATAL => 'all';"However, you should still heed the guidance earlier in this section against using use warnings FATAL => 'all';. Bestie I'm begging you. 🙏
If you want your program to be compatible with versions of Perl before 5.20, you must use use warnings FATAL => 'all'; instead. (In previous versions of Perl, the behavior of the statements use warnings 'FATAL';, use warnings 'NONFATAL'; and no warnings 'FATAL'; was unspecified; they did not behave as if they included the => 'all' portion. As of 5.20, they do.) 🌈
Okay bestie, so the warnings pragma is literally giving module-author main character energy — it has a whole lil toolkit you can use to report module-specific warnings back to whatever code called you, as long as that caller enabled warnings via the warnings pragma. Obsessed. 💖
Consider the module MyMod::Abc below.
package MyMod::Abc;
use warnings::register;
sub open {
my $path = shift;
if ($path !~ m#^/#) {
warnings::warn("changing relative path to /var/abc")
if warnings::enabled();
$path = "/var/abc/$path";
}
}
1;The call to warnings::register will create a new warnings category called MyMod::Abc, i.e. the new category name matches the current package name. The open function in the module will display a warning message if it gets given a relative path as a parameter. This warning will only be displayed if the code that uses MyMod::Abc has actually enabled them with the warnings pragma as below — note that a plain use warnings enables even warnings that have not yet been registered. 🫶
use warnings;
use MyMod::Abc;
...
abc::open("../fred.txt");The specific warning can be enabled or disabled, but only after the module has been imported:
# no warnings 'MyMod::Abc'; # error, unknown category before
# the module is loaded
use MyMod::Abc;
no warnings 'MyMod::Abc'; # ok after the module is loaded
...
abc::open("../fred.txt");It is also possible to test whether the pre-defined warnings categories are set in the calling module with the warnings::enabled function. Consider this snippet of code:
package MyMod::Abc;
sub open2 {
if (warnings::enabled("deprecated")) {
warnings::warn("deprecated",
"open2 is deprecated, use open instead");
}
open(@_);
}
sub open
...
1;The function open2 has been deprecated, so code has been included to display a warning message whenever the calling module has (at least) the deprecated warnings category enabled. Something like this, say.
use warnings 'deprecated';
use MyMod::Abc;
...
MyMod::Abc::open2($filename);Either the warnings::warn or warnings::warnif function should be used to actually display the warnings message. This is because they can make use of the feature that allows warnings to be escalated into fatal errors. So in this case
use MyMod::Abc;
use warnings FATAL => 'MyMod::Abc';
...
MyMod::Abc::open('../fred.txt');the warnings::warnif function will detect this and die after displaying the warning message.
The three warnings functions, warnings::warn, warnings::warnif and warnings::enabled can optionally take an object reference in place of a category name. In this case the functions will use the class name of the object as the warnings category.
Consider this example:
package Original;
no warnings;
use warnings::register;
sub new
{
my $class = shift;
bless [], $class;
}
sub check
{
my $self = shift;
my $value = shift;
if ($value % 2 && warnings::enabled($self))
{ warnings::warn($self, "Odd numbers are unsafe") }
}
sub doit
{
my $self = shift;
my $value = shift;
$self->check($value);
# ...
}
1;
package Derived;
use warnings::register;
use Original;
our @ISA = qw( Original );
sub new
{
my $class = shift;
bless [], $class;
}
1;The code below makes use of both modules, but it only enables warnings from Derived.
use Original;
use Derived;
use warnings 'Derived';
my $x = Original->new();
$x->doit(1);
my $y = Derived->new();
$x->doit(1);When this code is run only the Derived object, $y, will generate a warning.
Odd numbers are unsafe at main.pl line 7Notice also that the warning is reported at the line where the object is first used.
When registering new categories of warning, you can supply more names to warnings::register like this:
package MyModule;
use warnings::register qw(format precision);
...
warnings::warnif('MyModule::format', '...');✨ FUNCTIONS ✨
Note: The functions with names ending in _at_level were added in Perl 5.28. 💅
use warnings::register— Creates a new warnings category with the same name as the package where the call to the pragma is used. 🎀warnings::enabled()— Use the warnings category with the same name as the current package. Return TRUE if that warnings category is enabled in the calling module. Otherwise returns FALSE.warnings::enabled($category)— Return TRUE if the warnings category,$category, is enabled in the calling module. Otherwise returns FALSE.warnings::enabled($object)— Use the name of the class for the object reference,$object, as the warnings category. Return TRUE if that warnings category is enabled in the first scope where the object is used. Otherwise returns FALSE.warnings::enabled_at_level($category, $level)— Likewarnings::enabled, but$levelspecifies the exact call frame,0being the immediate caller.warnings::fatal_enabled()— Return TRUE if the warnings category with the same name as the current package has been set to FATAL in the calling module. Otherwise returns FALSE.warnings::fatal_enabled($category)— Return TRUE if the warnings category$categoryhas been set to FATAL in the calling module. Otherwise returns FALSE.warnings::fatal_enabled($object)— Use the name of the class for the object reference,$object, as the warnings category. Return TRUE if that warnings category has been set to FATAL in the first scope where the object is used. Otherwise returns FALSE.warnings::fatal_enabled_at_level($category, $level)— Likewarnings::fatal_enabled, but$levelspecifies the exact call frame,0being the immediate caller.warnings::warn($message)— Print$messageto STDERR. Use the warnings category with the same name as the current package. If that warnings category has been set to"FATAL"in the calling module then die. Otherwise return.warnings::warn($category, $message)— Print$messageto STDERR. If the warnings category,$category, has been set to"FATAL"in the calling module then die. Otherwise return.warnings::warn($object, $message)— Print$messageto STDERR. Use the name of the class for the object reference,$object, as the warnings category. If that warnings category has been set to"FATAL"in the scope where$objectis first used then die. Otherwise return.warnings::warn_at_level($category, $level, $message)— Likewarnings::warn, but$levelspecifies the exact call frame,0being the immediate caller.warnings::warnif($message)— Equivalent to:
if (warnings::enabled())
{ warnings::warn($message) }warnings::warnif($category, $message)— Equivalent to:
if (warnings::enabled($category))
{ warnings::warn($category, $message) }warnings::warnif($object, $message)— Equivalent to:
if (warnings::enabled($object))
{ warnings::warn($object, $message) }warnings::warnif_at_level($category, $level, $message)— Likewarnings::warnif, but$levelspecifies the exact call frame,0being the immediate caller.warnings::register_categories(@names)— This registers warning categories for the given names and is primarily for use by the warnings::register pragma.
Also go peek at Pragmatic Modules in perlmodlib and perldiag. 🌈
That’s the whole vibe, bestie. This page is from Perl v5.44.0, dated 2026-10-17, and it’s literally warnings(3perl). Stay iconic. 💅✨
📦 where this page comes from
- arch rolling: perl 5.44.0-1 · Artistic-1.0-Perl AND GPL-1.0-or-later
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms