Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 43 ยท Modules and Errors

CPAN and Dependency Management

Install and manage Perl dependencies: CPAN, cpanm, cpanfile, Carton, local::lib and perlbrew, plus how to judge module quality using MetaCPAN.

The Comprehensive Perl Archive Network (CPAN) is the big shared library behind Perl. Tens of thousands of distributions cover databases, web frameworks, parsing, dates, testing and much more, and installing one usually takes a single command. Using CPAN well is a core Perl skill: you save time, but you also take on code you did not write, so you need to install it cleanly and choose modules with care.

This lesson covers the install tools (cpan, cpanm), declaring dependencies in a cpanfile, keeping a project's modules separate with Carton and local::lib, managing Perl itself with perlbrew, and how to judge whether a module is worth depending on.

Perl is not installed on this site, so the commands below are read-only: run them in a terminal on your own machine. The interactive examples are small Bash and Python stand-ins that show the ideas (dependency files and version rules). Always check the current installation instructions for each tool, because details change between releases.

What CPAN is made of

Three pieces of CPAN

Distributions Archives of modules, tests and metadata.
MetaCPAN The search site and documentation viewer.
CPAN Testers Volunteers who test releases on many systems.
1 / 2

A distribution is what an author uploads: one or more modules plus tests, documentation and metadata such as the version and the dependencies. A single distribution can contain many modules. For example the distribution libwww-perl provides LWP::UserAgent and friends. When you install a module, the tool downloads its distribution, runs its tests, installs it and then repeats the process for everything it depends on.

Installing with cpan and cpanm

The cpan command ships with Perl:

Terminal
cpan List::MoreUtils

The first run asks a few configuration questions; accepting the defaults works for most people. A more popular choice for day-to-day use is cpanm, from the distribution App::cpanminus. It needs no configuration and prints little:

Terminal
cpanm Mojolicious
cpanm Try::Tiny Text::CSV
cpanm --notest Some::Slow::Module     # skip tests (only when you trust it)
cpanm --installdeps .                 # install what the project in . needs

Both tools install into the Perl you are running, which may be the system Perl. Installing into a system Perl needs administrator rights and can break tools that depend on it. Prefer one of the isolated approaches below.

You can check whether a module is already installed with a one-liner:

Terminal
perl -MText::CSV -e 'print "Text::CSV $Text::CSV::VERSION\n"'

If the module is missing, Perl prints Can't locate Text/CSV.pm in @INC, which is the same error you saw in Packages and Modules.

Declaring dependencies in a cpanfile

A cpanfile is a plain text file named cpanfile in your project root that lists what the project needs. It is written in Perl syntax.

PERL
requires 'perl', '5.036';
requires 'Mojolicious', '>= 9.0';
requires 'Text::CSV', '2.00';
requires 'Try::Tiny';

on 'test' => sub {
    requires 'Test::More', '0.98';
};

on 'develop' => sub {
    recommends 'Perl::Critic';
};

Each line names a module and, optionally, a version rule. A bare version such as '2.00' means "at least that version". The on 'test' and on 'develop' blocks hold dependencies needed only for running tests or for development. Committing the cpanfile to version control means anyone can reproduce your setup with cpanm --installdeps ..

Bash Stand-in: read a dependency file

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Isolating a project with Carton and local::lib

If two projects need different versions of the same module, installing everything globally causes conflicts. The solution is to give each project its own install folder.

local::lib points Perl and the installers at a directory in your home folder, so no administrator rights are needed:

Terminal
eval "$(perl -Mlocal::lib)"        # sets PERL5LIB and PATH for this shell
cpanm Text::CSV                    # now installs under ~/perl5

Carton builds on the same idea for a single project, similar to bundler in Ruby or npm in JavaScript. It reads your cpanfile, installs the modules into a local/ folder and writes a cpanfile.snapshot that records the exact versions chosen.

Terminal
cpanm Carton                       # install Carton itself
carton install                     # install everything from cpanfile into ./local
carton exec perl script.pl         # run with ./local on the module path
carton install --deployment        # on a server: use exactly the snapshot

Commit both cpanfile and cpanfile.snapshot. The cpanfile says what you want; the snapshot says what you actually got, so the server and your laptop run identical modules.

Python Stand-in: does a version meet the rule?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Real Perl versions are a little more subtle than this. Some modules use decimal versions such as 1.02 and others dotted ones such as v1.2.3, so use the installer's own comparison rather than writing your own. The stand-in only shows the idea of a minimum version.

Managing Perl itself with perlbrew

The Perl that came with your operating system is for the system's own scripts. For your projects, install your own Perl with perlbrew, which builds Perl versions into your home folder and lets you switch between them.

Terminal
perlbrew available                 # list installable versions
perlbrew install perl-5.42.0       # build and install (takes a few minutes)
perlbrew switch perl-5.42.0        # use it in every new shell
perlbrew list                      # show installed versions
perlbrew use perl-5.40.0           # use another one in this shell only

Perlbrew can create a library per project too (perlbrew lib create perl-5.42.0@myapp), which gives a similar isolation to local::lib. Many teams combine perlbrew for the interpreter with Carton for the modules. On Windows, Strawberry Perl already bundles a complete Perl with a compiler and cpanm, as covered in Installing and Running Perl.

Choosing quality modules

CPAN has several modules for almost every job, and they differ a lot in quality. Before you add a dependency, spend five minutes on MetaCPAN, the search site. Look at:

  • Recent activity. When was the last release? A stable module may be quiet for years, but a module with open bug reports and no releases for a long time is a warning sign.
  • Documentation. A clear synopsis with a runnable example is a good indicator.
  • CPAN Testers results. The module page links reports from many platforms and Perl versions. Mostly passes is good.
  • Dependencies. A module that pulls in a hundred others costs you install time and risk. Prefer small trees.
  • Bug tracker. Open issues that are answered are healthier than silence.
  • Licence. Make sure it fits your project. Most CPAN modules use the same terms as Perl itself.
  • Popularity. The number of distributions that depend on it ("reverse dependencies") shows what the community trusts.

Also prefer a core module when it does the job: JSON::PP, List::Util and File::Temp need no installation. When a core module is too slow or limited, the community often points to a faster alternative (for example Cpanel::JSON::XS for JSON), so read recent advice before choosing.

A CPAN module runs with all the permissions of your program. Treat a new dependency like any other third-party code: read what it does, check its maintainers, and pin the version with a snapshot. More on this in Security and Safe Perl.

A typical project workflow

Start a new project

Pick a Perl Use perlbrew to choose a version.
Write cpanfile List what the project needs.
carton install Modules land in ./local.
carton exec Run and test with those modules.

Commit cpanfile and cpanfile.snapshot.

1 / 2

On a teammate's machine, or on a server, the workflow is shorter: clone the repository and run carton install --deployment.

Common mistakes

  • Installing with sudo cpanm into the system Perl. Use local::lib, Carton or perlbrew instead.
  • No version information. If you commit nothing about versions, "it works on my machine" follows.
  • Skipping tests (--notest) as a habit. Tests catch missing system libraries early.
  • Choosing by the first search result. Compare two or three candidates on MetaCPAN.
  • Forgetting build tools. Some modules compile C code and need a compiler and system headers.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is a cpanfile?

    A cpanfile declares dependencies, with optional version rules and test or develop groups, so tools like cpanm and Carton can install them.
  2. 2. What does Carton record in cpanfile.snapshot?

    The snapshot pins the exact dependency versions, so installing with --deployment reproduces the same set elsewhere.
  3. 3. Why is installing project modules into the system Perl with sudo discouraged?

    System tools rely on the system Perl. Isolating modules with local::lib, Carton or perlbrew avoids that and lets each project use its own versions.
  4. 4. Which tool lets you install and switch between several versions of Perl itself?

    perlbrew builds Perl versions in your home directory and switches between them. Carton and cpanm manage modules, and MetaCPAN is a search site.
  5. 5. Which is a good signal when judging a CPAN module?

    Documentation, test reports from many platforms and an active tracker show a healthy module. A smaller dependency tree is also better.

Summary

  • CPAN is the shared archive of Perl distributions; MetaCPAN is where you search and read documentation.
  • Install with cpan or the quieter cpanm; prefer an isolated install over the system Perl.
  • Declare needs in a cpanfile, with optional versions and test or develop groups.
  • Carton installs a project's modules into ./local and pins versions in cpanfile.snapshot; local::lib gives per-user installs.
  • perlbrew installs and switches Perl versions.
  • Judge modules by activity, documentation, test reports, dependency count and licence, and prefer core modules when they are enough.

Next, learn how Perl programs report and recover from problems in Errors, die and eval.