MODULE::LOAD::CONDITIONAL(3perl)

🌸 NAME 🌸

Module::Load::Conditional — looking up module information, and loading modules at runtime 💅✨

(Yeah, the header up top squishes it to Module...itional(3perl) because terminals have no chill about column width. It's still our girl. And it lives in the Perl Programmers Reference Guide 🎀)

---

✨ SYNOPSIS ✨

use Module::Load::Conditional qw[can_load check_install requires];

my $use_list = {
        CPANPLUS        => 0.05,
        LWP             => 5.60,
        'Test::More'    => undef,
};

print can_load( modules => $use_list )
        ? 'all modules loaded successfully'
        : 'failed to load required modules';

my $rv = check_install( module => 'LWP', version => 5.60 )
            or print 'LWP is not installed!';

print 'LWP up to date' if $rv->{uptodate};
print "LWP version is $rv->{version}\n";
print "LWP is installed as file $rv->{file}\n";

print "LWP requires the following modules to be installed:\n";
print join "\n", requires('LWP');

### allow M::L::C to peek in your %INC rather than just
### scanning @INC
$Module::Load::Conditional::CHECK_INC_HASH = 1;

### reset the 'can_load' cache
undef $Module::Load::Conditional::CACHE;

### don't have Module::Load::Conditional issue warnings --
### default is '1'
$Module::Load::Conditional::VERBOSE = 0;

### The last error that happened during a call to 'can_load'
my $err = $Module::Load::Conditional::ERROR;

---

💖 DESCRIPTION 💖

Okay so Module::Load::Conditional gives you the cutest little ways to query — and then possibly load — literally any of the modules you've got installed on your system, all at runtime. No cap. 🫶

And here's the iconic part: it can load a whole squad of modules at once, or it can load none of them if even one of them refused to load. It also handles all the error checking and so forth for you, so you don't have to do it yourself. Main character energy, honestly. 👑

---

🔮 Methods 🔮

💫 $href = check_install( module => NAME [, version => VERSION, verbose => BOOL ] );

check_install is your vibe check for one specific question: is this module installed or not? You call it with these args, bestie:

• module — the name of the module you wanna verify. This one is a required key, no skipping 💅
• version — the version this module needs to be. This one is optional 🎀
• verbose — whether or not to be verbose about what it's doing. Defaults to $Module::Load::Conditional::VERBOSE

So what does it give back? If it couldn't find where the module was installed, you get undef. But if it did find the file, you get a hash reference with these keys:

• file — full path to the file that contains the module 🗂️
• dir — the directory, or more exactly the @INC entry, the module was loaded from
• version — the version number of the installed module. This is undef if the module had no version number (or an unparsable one), or if the variable $Module::Load::Conditional::FIND_VERSION was set to true. (Scroll down to the GLOBAL VARIABLES section for the tea 🍵)
• uptodate — a boolean telling you whether the module was found to be at least the version you specified. If you didn't specify a version, uptodate is always true as long as the module was found. And if no parsable version was found in the module, uptodate will also be true, because check_install had no way to verify it clearly. 🤷‍♀️

Also peep $Module::Load::Conditional::DEPRECATED, which affects the outcome of this value 👀

💫 $bool = can_load( modules => { NAME => VERSION [,NAME => VERSION] }, [verbose => BOOL, nocache => BOOL, autoload => BOOL] )

can_load takes a list of modules, optionally with version numbers attached, and figures out if it can load them. And the rule is ALL or NOTHING: if it can load ALL of them, it will. If one or more of them are unloadable, then none get loaded. Periodt. 💀

This is so useful when you've got More Than One Way (tm) to solve a problem in your program, and you only wanna keep walking down a path if every module on that path could be loaded — and not load them at all if they couldn't.

Under the hood it uses the load function or the autoload_remote function from Module::Load 🧚

can_load takes these arguments:

• modules — a hashref of module/version pairs. The version is the minimum version to load. If no version is given, any version is assumed to be good enough. Slay. ✨
• verbose — controls whether warnings get printed when a module fails to load. Default is to use the value of $Module::Load::Conditional::VERBOSE.
• nocache — can_load keeps its results in a cache, so it won't load the same module twice, and it won't even try to load a module that already failed to load before. By default can_load checks that cache, but you can override it by setting nocache to true. 🚫🗄️
• autoload — controls whether it imports the functions of a loaded module into the caller package. The default is no importing of any functions. For the details, go read the autoload function and the autoload_remote function from Module::Load 👑

💫 @list = requires( MODULE );

requires tells you what other modules a particular module requires. This is lowkey perfect when you're writing a module for public release and you're listing out its prerequisites 📝

requires takes but one argument: the name of a module. It will then first check if it can actually load that module, and return undef if it can't. Otherwise, it returns a list of modules and pragmas that would have been loaded on that module's behalf. 🌈

Note: the list require returns originated from your current perl and your current install. iykyk.

---

🧚 Global Variables 🧚

The behaviour of Module::Load::Conditional can be altered by changing these global variables:

🌟 $Module::Load::Conditional::VERBOSE

This controls whether Module::Load::Conditional issues warnings and explanations about why certain things may have failed. Set it to 0 and Module::Load::Conditional will not output any warnings. The default is 0;

🙈 Okay so fun little detail: the SYNOPSIS up top says the default is '1', and the POD down here says the default is 0. Both of those sentences are straight from the source, so make of that what you will. Not my business, I just report. 💅

🌟 $Module::Load::Conditional::FIND_VERSION

This controls whether Module::Load::Conditional tries to parse (and eval) the version out of the module you're trying to load. 🔍

If you don't wanna do that, set this variable to false. But understand: version comparisons become impossible, and Module::Load::Conditional can't tell you what module version you have installed. From a security or performance point of view, that might be exactly what you want. Note that the $FIND_VERSION code runs safely under taint mode. 🛡️

The default is 1;

🌟 $Module::Load::Conditional::CHECK_INC_HASH

This controls whether Module::Load::Conditional checks your %INC hash to see if a module is available. By default, only @INC gets scanned to see if a module is physically on your filesystem, or available via an @INC-hook. Set this variable to true and it'll trust any entries in %INC and hand them right back to you. 🫶

The default is 0;

🌟 $Module::Load::Conditional::FORCE_SAFE_INC

This controls whether Module::Load::Conditional sanitises @INC by removing ".". The current default setting is 0, but heads up — this may change in a future release. 👀

🌟 $Module::Load::Conditional::CACHE

This holds the cache of the can_load function. If you explicitly wanna nuke the current cache, just set this variable to undef. 💥

🌟 $Module::Load::Conditional::ERROR

This holds a string of the last error that happened during a call to can_load. Super useful to inspect when can_load returns undef. 🚨

🌟 $Module::Load::Conditional::DEPRECATED

This controls whether Module::Load::Conditional checks if a dual-life core module has been deprecated. Set it to true and check_install will return false for uptodate if a dual-life module is found to be loaded from $Config{privlibexp} 😭

The default is 0;

---

🌈 See Also 🌈

Module::Load

---

🐛 BUG REPORTS 🐛

Found a bug or some other issue? Please report it to <bug-module-load-conditional@rt.cpan.org>. Do it, bestie, they wanna hear from you 🫶

---

👑 AUTHOR 👑

This module is by Jos Boumans <kane@cpan.org>. Iconic behaviour.

---

💜 COPYRIGHT 💜

This library is free software; you may redistribute and/or modify it under the same terms as Perl itself. ✨

---

Okay that's the whole page, bestie! 🎀 This one's from perl v5.44.0, dated 2026-10-17 — the Module...itional(3perl) page from the Perl Programmers Reference Guide. Go forth and conditionally load things, you absolute legend 💅💖🦋