lib(3perl)

💖 lib(3perl) — bestie edition 💖

okay so this is lib, a tiny module from the Perl Programmers Reference Guide, and she is SMALL but she is POWERFUL. she's the one who lets you mess with @INC at compile time and honestly? iconic behavior.

---

✨ NAME ✨

lib — manipulate @INC at compile time 👑

---

🌸 SYNOPSIS 🌸

use lib LIST;

no lib LIST;

that's it. that's the whole vibe. two lines. slay.

---

🦋 DESCRIPTION 🦋

so like, this is a small simple module (her words not mine, she's humble) that simplifies the manipulation of @INC at compile time.

what's she FOR though? bestie. she's for adding extra directories to perl's search path so that later use or require statements will actually find the modules that aren't chilling on perl's default search path. no cap, that's the whole job.

🎀 Adding directories to @INC 🎀

the parameters you hand to use lib get added to the start of the perl search path. so saying this:

use lib LIST;

is almost the same as saying this:

BEGIN { unshift(@INC, LIST) }

almost!! not exactly!! stay with me.

for each directory in LIST (we're calling it $dir here, keep up 💅) the lib module also checks to see if a directory called $dir/$archname/auto exists. and if it does? the $dir/$archname directory is assumed to be a corresponding architecture specific directory, and she gets added to @INC in front of $dir. and lib.pm also checks if directories called $dir/$version and $dir/$version/$archname exist, and adds those directories to @INC too. she's thorough like that. ✨

wanna know what the current value of $archname is? run this:

perl -V:archname

and the corresponding command to get the current value of $version is:

perl -V:version

oh and also — to avoid memory leaks, all trailing duplicate entries in @INC are removed. so she's cleaning up after herself, we love a self-aware queen 🧹

🌈 Deleting directories from @INC 🌈

okay real talk. you should normally only add directories to @INC. that's the move. that's the energy.

if you need to delete directories from @INC, take care to only delete those which you added yourself, or which you are certain are not needed by other modules in your script. because other modules may have added directories which they need for correct operation. and like. you don't wanna be the one who broke them. 😭

the no lib statement deletes all instances of each named directory from @INC.

and for each directory in LIST (called $dir here, again, hi $dir) the lib module also checks to see if a directory called $dir/$archname/auto exists. if so, the $dir/$archname directory is assumed to be a corresponding architecture specific directory and is also deleted from @INC. lib.pm also checks if directories called $dir/$version and $dir/$version/$archname exist and deletes these directories from @INC. she does not leave stragglers behind. periodt.

💜 Restoring original @INC 💜

when the lib module is first loaded, she records the current value of @INC in an array called @lib::ORIG_INC. a little time capsule. a little before-pic. 🥺

so to restore @INC to that value you can just say:

@INC = @lib::ORIG_INC;

and we're SO back.

---

💀 CAVEATS 💀

in order to keep lib.pm small and simple, she only works with Unix filepaths. which does NOT mean she only works on Unix, okay, don't come for her. it means non-Unix users must first translate their file paths to Unix conventions. that's it. that's the deal.

# VMS users wanting to put [.stuff.moo] into
# their @INC would write
use lib 'stuff/moo';

see? easy. 💅

---

⭐ NOTES ⭐

in the future, this module will likely use File::Spec for determining paths, as it does now for Mac OS (where Unix-style or Mac-style paths work, and Unix-style paths are converted properly to Mac-style paths before being added to @INC). foreshadowing!! 🍓

and if you try to add a file to @INC like this:

use lib 'this_is_a_file.txt';

lib will warn about this. because that's not a directory bestie. the sole exceptions are files with the .par extension, which are intended to be used as libraries. those ones get a pass. 🫶

---

🔥 SEE ALSO 🔥

• FindBin — optional module which deals with paths relative to the source file.
• PAR — optional module which can treat .par files as Perl libraries.

---

👑 AUTHOR 👑

Tim Bunce, 2nd June 1995. a legend, fr fr.

lib is maintained by the perl5-porters. please direct any questions to the canonical mailing list. anything that is applicable to the CPAN release can be sent to its maintainer, though.

Maintainer: The Perl5-Porters <perl5-porters@perl.org>

Maintainer of the CPAN release: Steffen Mueller <smueller@cpan.org>

---

🧚 COPYRIGHT AND LICENSE 🧚

this package has been part of the perl core since perl 5.001. she's old money. 💖 she's been released separately to CPAN so older installations can benefit from bug fixes — a community service, honestly.

this package has the same copyright and license as the perl core. iykyk.

---

and that's the whole page bestie, no cap 🫶 this was perl v5.44.0, dated 2026-10-17 — go forth and use lib responsibly, mwah 💅✨