CPAN(1perl)

📦
version 5.44.0 · 2 versions
, in arch rolling

💖 CPAN — the perl pragma page, but make it cute 💖

okay so bestie, welcome to CPAN(1perl), from the Perl Programmers Reference Guide. yes that CPAN. the big one. the one you type when you want perl modules to just exist on your machine. let's get into it 🫶

✨ NAME ✨

cpan — easily interact with CPAN from the command line. that's it, that's the vibe. 💅

🌸 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, look at that. no arguments? shell mode. dot? installs whatever's in the current dir, iconic. 🦋

🎀 DESCRIPTION 🎀

okay so here's the tea: this script gives you a command interface to CPAN — and like, not a shell, bestie, we're being precise here. as of rn it uses CPAN.pm to do all the actual work, but it is not a one-shot command runner for CPAN.pm. those are different things and the manpage wants you to know it. 😌

💜 Options 💜

  • -a — creates a CPAN.pm autobundle with CPAN::Shell->autobundle. very "let me just snapshot everything" of it.
  • -A module [ module ... ] — shows the primary maintainers for the modules you name. yes, you can find out who to @ about it. 👑
  • -c module — runs a make clean inside the specified module's directories. tidy girl summer. 🧚
  • -C module [ module ... ] — shows the Changes files for the specified modules. receipts!! 😭
  • -D module [ module ... ] — shows the module details. it prints one line for every out-of-date module, and "out-of-date" here means modules that are locally installed but have newer versions on CPAN. each line has three columns: module name, local version, and CPAN version. three lil columns of truth. ✨
  • -f — forces the specified action when it normally would have failed. use it 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 — turns off CPAN.pm's attempts to lock anything. ⚠️ be careful with this one bestie, because you might end up with multiple scripts trying to muck around in the same directory. it's less of a concern if you're loading a special config with -j and that config sets up its own work directories.
  • -g module [ module ... ] — downloads the latest distribution of the module to the current directory.
  • -G module [ module ... ] — UNIMPLEMENTED. 💀

for the record, what it would do: download the latest distribution of the modules to the current directory, unpack each distribution, and create a git repository for each distribution.

if you actually want this feature, go check out Yanick Champoux's Git::CPAN::Patch distribution.

  • -h — prints a help message and exits. and when you specify -h, it ignores all the other options and arguments. main character behavior, honestly. it simply does not care.
  • -i module [ module ... ] — installs the specified modules. with no other switches, this switch is implied. so like, you were already doing it.
  • -I — loads local::lib (think of it like -I for loading lib paths). too bad -l was already taken. 😭
  • -j Config.pm — loads the file that has the CPAN configuration data. it should have the same format as the standard CPAN/Config.pm file, which defines $CPAN::Config as an anonymous hash.
  • -J — dumps the configuration in the same format that CPAN.pm uses. super useful for checking your config, and also for using that dump as a starting point for a new custom configuration. 🫶
  • -l — lists all installed modules with their versions.
  • -L author [ author ... ] — lists the modules by the specified authors.
  • -m — makes the specified modules.
  • -M mirror1,mirror2,... — a comma-separated list of mirrors to use for just this run. and the -P option can find them for you automatically.
  • -n — does a dry run, but doesn't actually install anything. (unimplemented) 🙈
  • -O — shows the out-of-date modules.
  • -p — pings the configured mirrors and prints a report.
  • -P — finds the best mirrors you could be using and uses them for the current session. glow-up for your download speeds. 🔥
  • -r — recompiles dynamically loaded modules with CPAN::Shell->recompile.
  • -s — drops you into the CPAN.pm shell. this command does this automatically if you don't specify any arguments, so it's lowkey the default.
  • -t module [ module ... ] — runs a make test on the specified modules.
  • -T — do not test modules. simply install them. (chaotic, but go off.)
  • -u — upgrades all installed modules. ⚠️ blindly doing this can really break things, so keep a backup. i'm not kidding, back it up.
  • -v — prints the script version and the CPAN.pm version, then exits.
  • -V — prints detailed information about the cpan client.
  • -w — UNIMPLEMENTED.

what it would do: turn on cpan warnings. it checks various things, like directory permissions, and tells you about problems you might have.

  • -x module [ module ... ] — finds 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. typos could never. ✨
  • -X — dumps all the namespaces to standard output.

🌈 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

(yes, Netscape::Booksmarks is spelled like that in the example. i'm not touching it, that's the source, we respect the source 💅)

🌸 Environment variables 🌸

so 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 skip 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).
  • PERL_MM_USE_DEFAULT — use the default answer for prompted questions. cpan(1) sets this to 1 unless it already has a value (even if that value is false).
  • CPAN_OPTS — same idea as PERL5OPT: a string of additional cpan(1) options to add to the ones you specify on the command line.
  • CPANSCRIPT_LOGLEVEL — the log level to use, whether with the embedded minimal logger or with Log::Log4perl if it's 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 everything worked, or a positive number if it thinks something failed. but ⚠️ note that in some cases it has to divine a failure from the output of things it does not control. for now, the exit codes are vague:

  1. 1 — an unknown error
  2. 2 — the was an external problem
  3. 4 — there was an internal problem with the script
  4. 8 — a module failed to install

(and yes, "The was an external problem" is exactly how it's written. we don't fix, we preserve. 😌)

🎀 TO DO 🎀

  • one shot configuration values from the command line

🦋 BUGS 🦋

  • none noted ✨

🌈 SEE ALSO 🌈

most behaviour — including environment variables and configuration — comes directly from CPAN.pm.

⭐ SOURCE AVAILABILITY ⭐

this code lives on 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. periodt.

👑 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.
  • Adam Kennedy pointed out that exit() causes problems on Windows where this script ends up with a .bat extension.

💖 AUTHOR 💖

brian d foy, "<bdfoy@cpan.org>"

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

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

and that's the whole page bestie, we ate and left no crumbs 🫶 this was perl v5.44.0, dated 2026-10-17, filed under CPAN(1perl). go install something cute. 💅✨

📦 where this page comes from