CPAN(1)

📦 version 5.42.3, in ubuntu stonking

💅 CPAN(1) — the perl programmers reference guide, but make it a group chat 💅

okay bestie, sit down, hydrate, because we're talking about cpan — she's the command-line bestie for CPAN, she lives in the Perl Programmers Reference Guide, and she comes in section 1. this whole page is literally her. let's go 🫶

✨ NAME ✨

cpan — easily interact with CPAN from the command line 🎀

🌸 SYNOPSIS 🌸

        # with arguments and no switches, installs specified modules
        cpan module_name [ module_name ... ]

        # with switches, installs modules with extra behavior
        cpan [-cfFimtTw] module_name [ module_name ... ]

        # use local::lib
        cpan -I module_name [ module_name ... ]

        # one time mirror override for faster mirrors
        cpan -p ...

        # with just the dot, install from the distribution in the
        # current directory
        cpan .

        # without arguments, starts CPAN.pm shell
        cpan

        # without arguments, but some switches
        cpan [-ahpruvACDLOPX]

like, that's genuinely the whole vibe in six little blocks. no notes. 💜

🦋 DESCRIPTION 🦋

so this script gives you a command interface (a command interface, NOT a shell, ok, we're being specific) to CPAN. right now it's using CPAN.pm to do the actual work, but ngl it is not a one-shot command runner for CPAN.pm. different thing. it's giving "middle manager with good intentions" and we love her for it. 💖

👑 Options 👑

  • -a — creates a CPAN.pm autobundle with CPAN::Shell->autobundle. autobundle era ✨
  • -A module [ module ... ] — shows the primary maintainers for the modules you name. like finding out who runs the account 👀
  • -c module — runs a make clean in the specified module's directories. scrubbing the timeline 🧼
  • -C module [ module ... ] — show the Changes files for the specified modules. the receipts, the whole lore 🍓
  • -D module [ module ... ] — show the module details. this prints one line for each out-of-date module (meaning: modules that are locally installed but have newer versions on CPAN). each line has three columns: module name, local version, and CPAN version. three columns, zero secrets 💅
  • -f — force the specified action, when it normally would have failed. use this to install a module even if its tests fail. and heads up: when you use this option, -i is not optional for installing a module when you need to force it:
        % cpan -f -i Module::Foo
  • -F — turn off CPAN.pm's attempts to lock anything. be careful bestie, because you might end up with multiple scripts trying to muck in the same directory. this isn't so much of a concern if you're loading a special config with -j, and that config sets up its own work directories. chaos is a choice etc.
  • -g module [ module ... ] — downloads to the current directory the latest distribution of the module. just a lil drop-off, no install 🎁
  • -G module [ module ... ] — UNIMPLEMENTED 🫠

download to the current directory the latest distribution of the modules, unpack each distribution, and create a git repository for each distribution.

if you want this feature, check out Yanick Champoux's Git::CPAN::Patch distribution. she's real, she exists 💀

  • -h — print a help message and exit. when you specify -h, it ignores all of the other options and arguments. -h is the main character and everyone else is background noise, periodt 👑
  • -i module [ module ... ] — install the specified modules. with no other switches, this switch is implied. she's the default queen, she doesn't even need to announce herself ✨
  • -I — load local::lib (think like -I for loading lib paths). too bad -l was already taken. tragic. we mourn 😭
  • -j Config.pm — load the file that has the CPAN configuration data. this should have the same format as the standard CPAN/Config.pm file, which defines $CPAN::Config as an anonymous hash. very demure, very anonymous hash 🎀
  • -J — dump the configuration in the same format that CPAN.pm uses. this is useful for checking the configuration as well as using the dump as a starting point for a new, custom configuration. glow-up blueprint fr fr 💅
  • -l — list all installed modules with their versions. the roster. the whole roster. 📋
  • -L author [ author ... ] — list the modules by the specified authors. stalking, but respectfully 🌸
  • -m — make the specified modules. 🔨
  • -M mirror1,mirror2,... — a comma-separated list of mirrors to use for just this run. the -P option can find them for you automatically. yes, she can do it for you, you don't have to ✨
  • -n — do a dry run, but don't actually install anything. (unimplemented) 💀
  • -O — show the out-of-date modules. the "we need to talk" list 😭
  • -p — ping the configured mirrors and print a report. checking if they're up, if they're responding, if they're still texting back 📡
  • -P — find the best mirrors you could be using and use them for the current session. matchmaking, but for mirrors 🦋
  • -r — recompiles dynamically loaded modules with CPAN::Shell->recompile. refresh refresh refresh 🔄
  • -s — drop in the CPAN.pm shell. this command does this automatically if you don't specify any arguments. she does it herself, no asking needed 💅
  • -t module [ module ... ] — run a make test on the specified modules. vibe check on the tests ✅
  • -T — do not test modules. simply install them. skipping the test, living dangerously, no cap 🌈
  • -u — upgrade all installed modules. blindly doing this can really break things, so keep a backup. i am literally begging you to keep a backup, bestie 😭
  • -v — print the script version and CPAN.pm version then exit. two versions, one flag 🎀
  • -V — print detailed information about the cpan client. the full biography, uncut 📖
  • -w — UNIMPLEMENTED 🫠

turn on cpan warnings. this checks various things, like directory permissions, and tells you about problems you might have. so helpful, so unavailable 💀

  • -x module [ module ... ] — find close matches to the named modules that you think you might have mistyped. this requires the optional installation of Text::Levenshtein or Text::Levenshtein::Damerau. spelling is hard, no shame 🍓
  • -X — dump all the namespaces to standard output. every single one. the whole multiverse 🌌

🌟 Examples 🌟

        # print a help message
        cpan -h

        # print the version numbers
        cpan -v

        # create an autobundle
        cpan -a

        # recompile modules
        cpan -r

        # upgrade all installed modules
        cpan -u

        # install modules ( sole -i is optional )
        cpan -i Netscape::Booksmarks Business::ISBN

        # force install modules ( must use -i )
        cpan -fi CGI::Minimal URI

        # install modules but without testing them
        cpan -Ti CGI::Minimal URI

screenshot this. put it in the group chat. it's giving tutorial and i ate 🔥

yes, the Netscape::Booksmarks spelling in the example is exactly how it appears. do not "fix" it. character for character, bestie. 🫶

🧚 Environment variables 🧚

there are several components in CPAN.pm that use environment variables. the build tools, ExtUtils::MakeMaker and Module::Build, use some, while others matter to the levels above them. some of these are specified by the Perl Toolchain Gang:

Lancaster Consensus: https://github.com/Perl-Toolchain-Gang/toolchain-site/blob/master/lancaster-consensus.md

Oslo Consensus: https://github.com/Perl-Toolchain-Gang/toolchain-site/blob/master/oslo-consensus.md

  • NONINTERACTIVE_TESTING — assume no one is paying attention and skips prompts for distributions that do that correctly. cpan(1) sets this to 1 unless it already has a value (even if that value is false). it doesn't overwrite your choices, that's respect 💜
  • PERL_MM_USE_DEFAULT — use the default answer for a prompted questions. cpan(1) sets this to 1 unless it already has a value (even if that value is false). again with the not-overwriting. queen behaviour 👑
  • CPAN_OPTS — as with PERL5OPT, a string of additional cpan(1) options to add to those you specify on the command line. extra toppings, no charge 🍓
  • CPANSCRIPT_LOGLEVEL — the log level to use, with either the embedded, minimal logger or Log::Log4perl if it is installed. possible values are the same as the Log::Log4perl levels: TRACE, DEBUG, INFO, WARN, ERROR, and FATAL. the default is INFO. ✨
  • GIT_COMMAND — the path to the git binary to use for the Git features. the default is /usr/local/bin/git. 📍

💀 EXIT VALUES 💀

the script exits with zero if it thinks that everything worked, or a positive number if it thinks that something failed. note, however, that in some cases it has to divine a failure by the output of things it does not control. so she's guessing a lil bit. for now, the exit codes are vague:

        1       An unknown error

        2       The was an external problem

        4       There was an internal problem with the script

        8       A module failed to install

(yes, "The was an external problem" — that's the original text, we keep it exactly, no editing the artefact 💖)

🌈 TO DO 🌈

  • one shot configuration values from the command line

manifesting this one for her, honestly 🙏

🙈 BUGS 🙈

  • none noted

not a single one. iconic. flawless. we simply do not have problems here 💅✨

🔗 SEE ALSO 🔗

most behaviour, including environment variables and configuration, comes directly from CPAN.pm. go read her too, she's the source 🫶

👑 SOURCE AVAILABILITY 👑

this code is in Github in the CPAN.pm repository:

        https://github.com/andk/cpanpm

the source used to be tracked separately in another GitHub repo, but the canonical source is now in the above repo. one repo to rule them all, no cap ✨

🎀 CREDITS 🎀

Japheth Cleaver added the bits to allow a forced install (-f). 🫡

Jim Brandt suggest and provided the initial implementation for the up-to-date and Changes features. (yes, "suggest" like that, original text, we keep it 💖)

Adam Kennedy pointed out that exit() causes problems on Windows where this script ends up with a .bat extension. shoutout Adam 🙌

🌸 AUTHOR 🌸

brian d foy, "<bdfoy@cpan.org>" — icon, legend, the moment 💜

Copyright (c) 2001-2015, brian d foy, All Rights Reserved.

You may redistribute this under the same terms as Perl itself.

okay that's the whole page bestie, you're officially a cpan expert, go install something and text me how it went 🦋

this little love letter was brought to you by perl v5.42.3, dated 2026-08-17, and filed under CPAN(1) — mwah, bye 💅💖✨

📦 where this page comes from