Install and Inspect Perl Modules Safely with cpan

cpan is the command-line front end to CPAN.pm, and this guide gets you identifying the client, inspecting a module and installing it deliberately. The point is doing that without turning a routine dependency change into a full system upgrade. These examples use the cpan script shipped with Perl 5.38.2 on Ubuntu, alongside CPAN.pm 2.36. Allow 10 to 20 minutes for a first run, since CPAN.pm may need one-time configuration and a mirror download.

Before you start

You need a shell, a working network connection, Perl itself, and the name of the distribution or module you are after. This guide uses Example::Module as a visible placeholder: swap in a real module name before you press Return, and never paste the placeholder into a production command.

Installing into the system Perl normally needs elevated privileges. Reach for a project or user library instead when that fits better. A module may run build steps and tests, so read its documentation and look over the proposed dependency changes before accepting them. Do not reach for -T just to force a failed installation to finish: it disables the module's tests.

Checkpoint 1: identify the client

Start by confirming which executable you are actually running, and record its versions:

command -v cpan
dpkg-query -W -f='${Package} ${Version}\n' perl
cpan -v

On the reference system the executable is /usr/bin/cpan, the installed Debian package is Perl 5.38.2-3.2ubuntu0.6, and the client reports script version 1.678 alongside CPAN.pm 2.36. Your package revision or CPAN.pm version may well differ. Keep this output with the change record, because client behaviour is version-specific.

Checkpoint 2: inspect before changing anything

Module details tell you whether something is already installed and whether CPAN has a newer release. This is a read-only check:

cpan -D Example::Module

The details report lists one line for every locally installed module that is out of date, giving the module name, local version and CPAN version. No useful result usually means a spelling or namespace problem. The client also offers a close-match search, though it depends on the optional Text::Levenshtein or Text::Levenshtein::Damerau module:

cpan -x Exampel::Module

Do not mistake a module name such as HTTP::Tiny for a distribution archive name. cpan accepts module names and resolves the distribution itself through CPAN.pm.

Checkpoint 3: install one named module

With no switches, cpan treats a named argument as a module to install; the explicit form just states that intent plainly:

sudo cpan -i Example::Module

Reserve sudo for when you have actually decided the module belongs in the system Perl. On a managed machine, check with the package owner whether an operating-system package is preferred instead. Without elevated privileges, CPAN.pm may offer to set up a user library such as local::lib, which keeps files out of system directories but changes how Perl locates them: check the generated shell environment before trusting the installation.

By default cpan runs each module's tests as part of installing it. Watch the final status line and the process exit value: cpan exits zero when it believes the operation worked, and a positive value when it believes something failed. The documented codes are 1 for an unknown error, 2 for an external problem, 4 for an internal problem, and 8 when a module fails to install.

if sudo cpan -i Example::Module; then
    echo 'module installation reported success'
else
    status=$?
    echo "cpan failed with status $status" >&2
fi

Checkpoint 4: verify the installed Perl view

Ask Perl where it actually finds the module and load it, replacing a version check with an API check the module documents:

perl -MExample::Module -e 'print $INC{"Example/Module.pm"}, "\n"'
perl -MExample::Module -e 'print $Example::Module::VERSION // "no version variable", "\n"'

A path under the library you intended confirms which Perl installation is in play. A missing-module error usually comes down to one of three causes: cpan installed into a different Perl, the user library environment never loaded, or the installation genuinely failed. Compare command -v perl, perl -V and the cpan output before you try again.

Useful read-only operations

These switches answer focused questions without installing anything:

For a one-off mirror choice, pass a comma-separated list to -M. -P finds suitable mirrors for the current session. Neither switch permanently fixes a broken network path, proxy or certificate problem.

Configuration and repeatability

Running cpan with no arguments opens the CPAN.pm shell, handy for interactive work but easy to lose track of which command changed what. For repeatable work, keep the module name and switches in a shell script or build configuration, and record the Perl version alongside them.

-j Config.pm loads a particular CPAN configuration file, which must define $CPAN::Config as an anonymous hash in the same format as the standard CPAN/Config.pm. Never point this at an untrusted file: it controls how CPAN.pm behaves and can affect build directories, mirrors and installation paths.

Environment variables can quietly change a run. CPAN_OPTS adds cpan options to whatever is already on the command line. PERL_MM_USE_DEFAULT and NONINTERACTIVE_TESTING affect prompts, and cpan sets each to 1 when unset. In automation, set these on purpose and capture logs rather than assuming a prompt got answered the way you wanted.

Safety boundaries

Never start with sudo cpan -u. It upgrades every installed module, can replace dependencies that unrelated programs rely on, and the manual itself warns that doing it blindly can break things. Take a backup and use a controlled environment if a broad upgrade is genuinely needed; there is no general undo, so recovery means restoring the previous library or reinstalling known package versions.

Similarly, -f forces an action through even when tests fail, and it needs to be paired with -i when forcing an installation:

sudo cpan -f -i Example::Module

Reach for this only once you have read the failure and decided it is understood and acceptable. -T skips tests rather than fixing whatever they caught; -c and -m clean or build module directories, so use them only once you understand CPAN.pm's chosen work area. The -n dry-run option is currently documented as unimplemented, so do not treat it as a safety net.

Done means