CPAN(1)

📦
version 5.34.0 · 2 versions
, in ubuntu jammy

💅 cpan — the CPAN(1) manual but make it make sense

okay bestie, gather round, because this page is literally the glow-up your command line has been waiting for 🫶

✨ 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]

🦋 DESCRIPTION 🦋

So this script is a command interface — a command interface, not a shell, okay, we're keeping those two separate — to CPAN. Right now it's using CPAN.pm to do all the actual heavy lifting, but heads up: it is not a one-shot command runner for CPAN.pm. Different vibe entirely. 💅

🎀 Options 🎀

  • -a — makes a CPAN.pm autobundle with CPAN::Shell->autobundle.
  • -A module [ module ... ] — shows you the primary maintainers for the modules you named. 👑
  • -c module — runs a make clean in the specified module's directories.
  • -C module [ module ... ] — shows the Changes files for the modules you named.
  • -D module [ module ... ] — shows the module details. It prints one line for each out-of-date module (and by "out-of-date" we mean modules installed locally that have newer versions up on CPAN). Every line has three columns: module name, local version, and CPAN version. 📋
  • -f — forces the specified action when it would normally have failed. Use it to install a module even if its tests fail. And listen: 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 could 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. The idea: 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. When you specify -h, it ignores all of the other options and arguments. iconic behaviour honestly.
  • -i module [ module ... ] — installs the specified modules. With no other switches, this switch is implied.
  • -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 the 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. The -P option can find them for you automatically. ✨
  • -n — do a dry run, but don'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.
  • -r — recompiles dynamically loaded modules with CPAN::Shell->recompile.
  • -s — drops you into the CPAN.pm shell. This command does it automatically if you don't specify any arguments.
  • -t module [ module ... ] — runs a make test on the specified modules.
  • -T — do not test modules. Just install them. no thoughts, just install 💅
  • -u — upgrades all installed modules. Doing this blindly can really break things, so keep a backup. fr fr, back it up.
  • -v — prints the script version and CPAN.pm version, then exits.
  • -V — prints detailed information about the cpan client.
  • -w — UNIMPLEMENTED. The idea was to 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 one requires the optional installation of Text::Levenshtein or Text::Levenshtein::Damerau.
  • -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

🧚 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 Concensus: <https://github.com/Perl-Toolchain-Gang/toolchain-site/blob/master/lancaster-consensus.md>

Oslo Concensus: <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 — as with PERL5OPT, a string of additional cpan(1) options to add to those you specify on the command line.
  • 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. But ngl, in some cases it has to divine a failure by the output of things it does not control. 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

💀 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 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. 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 🫶 this one's from perl v5.34.0, dated 2026-09-03, and yeah the manual name up top is CPAN(1) — slay, you read the whole thing, so proud of you 💖✨

📦 where this page comes from