Install Perl Modules Safely with cpan5.38-x86_64-linux-gnu

This guide uses your installed CPAN client to check its identity, inspect a module and install it without quietly skipping its tests. The executable is /usr/bin/cpan5.38-x86_64-linux-gnu, provided by libperl5.38t64 version 5.38.2-3.2ubuntu0.6, running CPAN.pm 2.36. Allow roughly fifteen minutes for a first installation, longer if a distribution carries native dependencies or prompts that need looking into.

You need a shell, a working Perl installation, and a module name you have already chosen deliberately. Plain inspection commands need no elevated privileges; installing into the system Perl normally does, so use your distribution's package manager instead whenever a module is already packaged for Ubuntu and that is the better maintenance choice.

1. Confirm which client you will run

Several CPAN front ends exist side by side, and the command name here is versioned on purpose. Check the path and the local CPAN.pm version before trusting an old command example:

$ command -v cpan5.38-x86_64-linux-gnu
/usr/bin/cpan5.38-x86_64-linux-gnu
$ perl5.38-x86_64-linux-gnu -MCPAN -e 'print "CPAN.pm $CPAN::VERSION\n"'
CPAN.pm 2.36

The client reports its own script and CPAN.pm versions through -v, but a first run may trigger CPAN.pm configuration, which can ask where to put user modules and can create files in your home directory. Treat that as a setup decision, not a harmless version check. The command above identifies the installed library without walking into that dialogue.

2. Read the built-in help without installing anything

-h lists the options this installed client supports:

$ cpan5.38-x86_64-linux-gnu -h
NAME
    cpan - easily interact with CPAN from the command line
...
  Options
    -i module [ module ... ]
        Install the specified modules.

The exact help text shifts between Perl releases. What matters is that -h ignores every other option and argument, then exits successfully. A bare module name implies -i, so these two forms carry the same intent:

$ cpan5.38-x86_64-linux-gnu -i Module::Name
$ cpan5.38-x86_64-linux-gnu Module::Name

Hold off on pasting either installation command until you have checked the module name and decided where its files should end up.

3. Choose system or user installation deliberately

CPAN.pm checks whether the current user can write to the Perl library directories. If not, first-run setup offers a local library, sudo, or manual configuration. A local library leaves the system Perl untouched but means every future shell and service needs to know about it; a system installation is visible to everyone but needs administrative authority and can drift from the package manager's own records.

Never answer a configuration prompt on autopilot. Stop and decide who should own the module. For a system-wide install, run the client with whatever privilege your host's policy demands:

$ sudo cpan5.38-x86_64-linux-gnu -i Module::Name

sudo is an elevated action here: it can compile and run distribution-provided build steps as root, so check the module's provenance and the command itself before accepting the prompt. Choosing a local library instead means keeping its configuration inside your own account and not mixing its paths into a service until you have tested that service's environment.

4. Install one known module with tests enabled

Swap Module::Name for the exact distribution you need. CPAN.pm normally fetches the distribution, builds it, runs its tests, and installs it once those stages succeed:

$ sudo cpan5.38-x86_64-linux-gnu -i Module::Name
Running install for module 'Module::Name'
...
Result: PASS
  /usr/bin/make install  -- OK

Output varies with the build system and dependency versions in play. What matters is a successful test phase followed by a successful install. Verify the module through Perl itself rather than guessing its file path:

$ perl5.38-x86_64-linux-gnu -MModule::Name -e 'print "loaded\n"'
loaded

If the module targets a different Perl interpreter, run that same interpreter for both the install and the verification: a module installed into one Perl library path is not automatically visible to every Perl binary on the machine.

5. Treat failed tests as a stop sign

A failed test means the distribution could not establish the behaviour it expects on this machine. Read the failure, check the prerequisites and compiler output, then decide whether the module version or platform actually fits. Do not force the installation through just to make the command finish.

-f forces an action that would normally fail, and the manual requires -i alongside it for installation:

$ sudo cpan5.38-x86_64-linux-gnu -f -i Module::Name

Doing this can leave you running code that failed its own tests. Treat it as a security and reliability boundary, not a routine recovery step: record the failed tests, keep a rollback plan, and prefer a packaged or fixed release when one exists. If an incomplete installation has already happened, remove or replace the module through the same owner that installed it, then check the interpreter's load path again.

6. Keep inspection separate from state changes

Some switches only read metadata; others change the machine. -A shows primary maintainers, -C shows a module's Changes file, -D lists local and CPAN versions for anything out of date, and -p pings configured mirrors. These may reach out to CPAN or use existing configuration, but none of them install anything.

By contrast, -u upgrades every installed module, and the manual explicitly warns that doing this blindly can break things: never use it as a routine maintenance shortcut. -T disables testing entirely, removing a genuinely valuable safety check, so reserve it for a documented case where you understand the consequence. The -n dry-run option is marked unimplemented in this installed client, so it is not a reliable preview either.

With no arguments at all, cpan opens the CPAN.pm shell, an interactive environment rather than a one-shot command runner. Prefer a complete command captured in a reviewed shell history or script whenever you need something repeatable.

7. Recover without guessing

The client returns zero when it believes the operation worked and a positive value when it believes something failed. Its documented codes are broad: 1 unknown error, 2 external problem, 4 internal problem, and 8 module installation failure. Capture the status right away:

cpan5.38-x86_64-linux-gnu -i Module::Name
status=$?
printf 'cpan exit status: %s\n' "$status"
exit "$status"

A zero status is no substitute for actually checking that the requested module loads. For a non-zero status, keep the build output, fix the named dependency or configuration problem, and rerun the same operation: do not reach for -f or -T just because the first attempt was inconvenient. If a system install already changed a module and you need to undo it, use the package or CPAN ownership information to remove that exact module, reinstall the known-good version, and rerun the load check.