App::Cpan(3perl)

📦

version 5.44.0 · 14 versions

💖 App::Cpan — the `cpan` command, but make it make sense 💖

okay bestie, so this is the manual page for App::Cpan 💅 (that's the module behind the cpan command you keep typing). It lives in the Perl Programmers Reference Guide, and it's basically the group chat between you and CPAN. sit down, grab a strawberry drink 🍓, we're doing this.

✨ NAME ✨

App::Cpan — easily interact with CPAN from the command line. that's it, that's the whole vibe. no cap. 🫶

🌈 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 gives you a command interface to CPAN — and no, bestie, it is not a shell (well, it can drop you into one, but that's a whole thing, we'll get there 👀). Right now it uses CPAN.pm to do the actual work, but it is not a one-shot command runner for CPAN.pm. it's its own whole icon. ✨

🎀 Options 🎀

-a — creates a CPAN.pm autobundle with CPAN::Shell->autobundle. iconic behavior honestly.
-A module [ module ... ] — shows you the primary maintainers for the modules you named. who's running this account 👑
-c module — runs a make clean in the specified module's directories. tidy up, we love a clean girl 🌸
-C module [ module ... ] — show the Changes files for the specified modules. the receipts, the lore 📜
-D module [ module ... ] — show the module details. this prints one line for each out-of-date module (meaning: modules you have locally, but there are newer versions up on CPAN). each line has three columns: module name, local version, and CPAN version. three columns, no notes 💅
-f — force the specified action, even when it normally would have failed. use this 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 — turn off CPAN.pm's attempts to lock anything. ⚠️ you should be careful with this since you might end up with multiple scripts trying to muck in the same directory. it's not so much 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. just the download, no install. window shopping 🛍️
-G module [ module ... ] — UNIMPLEMENTED. 😭 supposed to download the latest distribution of the modules to the current directory, 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.
-h — print a help message and exit. and when you specify -h, it ignores all of the other options and arguments. -h said main character energy only, everyone else go home 👑
-i module [ module ... ] — install the specified modules. with no other switches, this switch is implied. it's giving "you didn't even have to ask" 💅
-I — load local::lib (think like -I for loading lib paths). too bad -l was already taken. 💀
-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. if the file does not exist, cpan dies. 😭 no file, no vibes.
-J — dump the configuration in the same format that CPAN.pm uses. super useful for checking the configuration and for using the dump as a starting point for a new, custom configuration. reuse, recycle, slay ♻️
-l — list all installed modules with their versions. the roll call 📋
-L author [ author ... ] — list the modules by the specified authors. the author's whole catalog 🎀
-m — make the specified modules. building, not installing 🔨
-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. one-time mirror, no commitment 💫
-n — do a dry run, but don't actually install anything. (unimplemented) 🫠
-O — show the out-of-date modules. who's falling behind, no judgement 📉
-p — ping the configured mirrors and print a report. mirror wellness check 🩺
-P — find the best mirrors you could be using, and use them for the current session. glow up your mirrors ✨
-r — recompiles dynamically loaded modules with CPAN::Shell->recompile. refresh, reboot, recompile 🔄
-s — drop in the CPAN.pm shell. this command does this automatically if you don't specify any arguments. so like, cpan with nothing is already this 🐚
-t module [ module ... ] — run a make test on the specified modules. test, don't trust 🧪
-T — do not test modules. simply install them. living dangerously, we respect it 😌
-u — upgrade all installed modules. ⚠️ blindly doing this can really break things, so keep a backup. seriously bestie, back it up. fr fr.
-v — print the script version and CPAN.pm version, then exit. the ID check 🪪
-V — print detailed information about the cpan client. the full biopsy 🩻
-w — UNIMPLEMENTED. 😭 supposed to turn on cpan warnings: this checks various things, like directory permissions, and tells you about problems you might have.
-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. typos happen, live laugh love 🦋
-X — dump all the namespaces to standard output. every single one. information overload, we love 📚

🌸 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 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).
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).
CPAN_OPTS — as with PERL5OPT, a string of additional cpan(1) options to add to those you specify on the command line. secret bonus settings 🎁
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.

💅 Methods 💅

run( ARGS ) — just do it. 😤

The run method returns 0 on success and a positive number on failure. see the section on EXIT CODES for details on the values.

CPAN.pm sends all the good stuff either to STDOUT, or to a temp file if $CPAN::Be_Silent is set. I have to intercept that output so I can find out what happened.

Stolen from File::Path::Expand. (borrowed with love 🫶)

🔥 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. 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

(and yes, "The was an external problem" is what the original says. typo stays, I don't make the rules 💀)

⭐ TO DO ⭐

There is initial support for Log4perl if it is available, but I haven't gone through everything to make the NullLogger work out correctly if Log4perl is not installed.
When I capture CPAN.pm output, I need to check for errors and report them to the user.
Warnings switch
Check then exit

the list is giving "we'll get to it" energy ✨

💀 BUGS 💀

none noted

we love a flawless queen. no cap. 👑

🌈 SEE ALSO 🌈

CPAN, App::cpanminus

👑 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. canon is canon, bestie 📌

🫶 CREDITS 🫶

Japheth Cleaver added the bits to allow a forced install (-f).
Jim Brandt suggested 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
David Golden helps integrate this into the CPAN.pm repos.
Jim Keenan fixed up various issues with _download

they all ate, honestly 💅

🌸 AUTHOR 🌸

brian d foy, <bdfoy@cpan.org>

💖 COPYRIGHT 💖

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

okay that's the whole page, you're basically a CPAN girlie now 🎀 this was App::Cpan(3perl) — Perl Programmers Reference Guide, shipped with perl v5.44.0, dated 2026-10-17. mwah 💋 go install something. bye bestie! 🦋✨

📦 where this page comes from

arch rolling: perl 5.44.0-1 · Artistic-1.0-Perl AND GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms