Install a CPAN Perl Module Locally and Verify It

You will unpack a CPAN module, build it, run its tests, and install it under a directory you own. The final Perl check will use that directory without changing the system Perl installation. Allow 15 to 30 minutes, plus any time needed to resolve the module's dependencies. These examples use Perl 5.38.2 and the perl-doc 5.38.2-3.2ubuntu0.6 documentation package installed on this machine.

The workflow is deliberately conservative. It does not use sudo, overwrite a system library, or delete the source archive. Read the module's README and INSTALL files before building: a particular distribution can have requirements that the general Perl documentation cannot predict.

1. Check whether the module is already available

Replace Some::Module with the module name you actually need. This read-only command tries to load it and exits immediately:

$ perl -MSome::Module -e 1

A successful command prints nothing and returns status 0. Check that status straight away:

$ printf 'load status: %s\n' "$?"
load status: 0

If Perl reports that it cannot locate the module, show the library search path before deciding that it is absent:

$ perl -e 'print join("\n", @INC), "\n"'

A module may exist in a directory that is not in this interpreter's @INC. If you only need it for one project, a local installation is usually clearer than changing a system directory.

2. Prepare an isolated working directory

Make a directory for the archive and its extracted source. This is an ordinary user command:

$ mkdir -p "$HOME/src/perl-modules"
$ cd "$HOME/src/perl-modules"

Download the distribution from its CPAN page using your normal trusted download method, then replace the placeholder filename below with the file you obtained. Do not run build commands from an untrusted directory containing unrelated files.

$ ls -l Some-Module-1.23.tar.gz
$ tar -tzf Some-Module-1.23.tar.gz | head

The listing should show a distribution directory and its files. If the archive is a zip file, use a zip-capable extractor instead and then inspect the extracted directory. Stop if the download is incomplete or the archive has an unexpected layout.

3. Decompress and unpack the archive

For the usual .tar.gz distribution, extract it into the working directory:

$ tar -xzf Some-Module-1.23.tar.gz
$ cd Some-Module-1.23
$ ls

Look for Makefile.PL, a Build.PL, or the build instructions named by the module's documentation. The traditional workflow described by perlmodinstall uses Makefile.PL. Do not assume that every CPAN distribution uses the same build system.

Extraction creates files in the current directory. If you unpacked the wrong archive, do not blindly remove a directory that might contain your work. Leave it in place, identify the correct distribution, and use a fresh working directory.

4. Read the distribution instructions

Read the local documentation before running generated build code:

$ less README
$ less INSTALL

Check for required Perl versions, external libraries, compiler requirements, platform limitations, and extra configuration. A module containing XS, C, or other native source may need a compiler and development headers. A failed test caused by a missing system library is not fixed by repeating the install command.

5. Generate a Makefile for a user-owned prefix

Run the module's Makefile generator with a prefix you own:

$ perl Makefile.PL PREFIX="$HOME/perl5"
Writing Makefile for Some::Module

The exact messages vary. A successful run should create a Makefile and should not ask to write under /usr. The prefix is a destination choice, not a module name. Keep it consistent for the test and install steps.

If the distribution has a different documented generator, follow that documentation instead. Do not add sudo merely because a default configuration points at a system directory; use a user-owned prefix when the module supports it.

6. Build and test before installing

Build the module and run its test suite from the extracted source directory:

$ make
$ make test

Successful tests normally end with a summary such as Result: PASS, although the wording and number of tests depend on the distribution. Confirm the exit status after the test command:

$ printf 'test status: %s\n' "$?"
test status: 0

Do not install a distribution whose tests fail without understanding why. Save the failure output, check the stated prerequisites, and consult the module author or CPAN test reports. The build may have created generated files, but that is reversible by discarding this disposable extracted directory after you have recorded the diagnostic.

7. Install and add the prefix to Perl's search path

Only after the tests pass, install into the same prefix:

$ make install
Installing ...

This changes files below $HOME/perl5, not the system library. To use the module in one program, add the matching library directory with use lib before loading it. The exact subdirectory is shown by the install output; a common layout is lib/perl5, so verify rather than guessing:

$ find "$HOME/perl5" -type f -name 'Module.pm' -o -name '*.so' | head

For a temporary shell check, set PERL5LIB to the installed library path. Replace the placeholder path if the install output used another one:

$ export PERL5LIB="$HOME/perl5/lib/perl5${PERL5LIB:+:$PERL5LIB}"
$ perl -MSome::Module -e 1
$ printf 'load status: %s\n' "$?"
load status: 0

For application code, prefer a deliberate use lib path or the project's dependency tooling rather than relying on an unrecorded interactive shell export.

8. Recover from a bad install

A user-prefix install can be removed without touching system Perl, but removal is still destructive. First list the files under the prefix and keep a copy of any local work. If this prefix contains only this module, remove the specific prefix only when you are certain it is no longer needed:

$ find "$HOME/perl5" -maxdepth 3 -type f -print
$ rm -rf "$HOME/perl5"

The rm -rf command is irreversible and is included only as an explicit recovery example. Do not run it if the prefix contains other modules. Instead remove the installed files recorded by the module's install manifest, or recreate a clean prefix for the next attempt. Unset the temporary path afterwards if you no longer need it:

$ unset PERL5LIB