Perl CPAN

ID

cpan

Links

Home page · Documentation · Repository · Wikipedia

Upstream stars

⭐ 90

Last commit

2026-09-12

Version requirement

>= 1.64

Platforms

🅱️ BSD · 🐧 Linux · 🍎 macOS · ⨂ Unix · 🪟 Windows

Operations

installed · outdated · install · upgrade · upgrade_all

purl types

pkg:cpan/

CLI name

cpan

Forced environment

PERL_MM_USE_DEFAULT=1

Issues and PRs

📦 manager: cpan

Source

cpan.py

The cpan client of the Comprehensive Perl Archive Network.

The tracked version is CPAN.pm’s library version, not the cpan script version printed on the same line.

Installs may require sudo when using the system Perl; local::lib gives user-local installs instead. The write operations carry dormant privileged markers: --sudo or a sudo = true override escalates them, while nothing escalates by default.

Caution

Perl’s core modules (warnings, feature, POSIX, B, and the like) exist only inside Perl itself, with no standalone CPAN distribution, so their versions are tied to whichever Perl you run. cpan -O reports them as outdated whenever that Perl trails the newest one CPAN has indexed, yet cpan -u can never upgrade them in place, since only a newer Perl carries newer core modules. mpm relays both faithfully. This holds for any Perl, whether the macOS system one or a Homebrew install.

On the macOS system Perl at /usr/bin/perl, that Perl sits on the sealed, read-only system volume and cannot be replaced even with sudo, so the list never clears.

With a writable, user-controlled Perl ahead on your PATH (via brew install perl, since mpm drives whichever cpan comes first), the list does clear, but on a recurring delay: each yearly Perl release reaches CPAN before Homebrew publishes its bottle, so for a few weeks cpan -O flags the new release’s core modules as outdated against your current ones. Perl 5.44.0, released 2026-07-15, opened one such window against the 5.42 series Homebrew still bottled. Running brew upgrade perl once the new bottle lands moves your core modules to the new set and clears the list, until the next release reopens the window.

If you do not track Perl modules with cpan at all, disable the manager entirely: set cpan = false in your mpm config, or pass --no-cpan. See #1983 for the original report.

What mpm adds to cpan

mpm reaches across every manager at once, not cpan alone: mpm installed and mpm outdated cover cpan alongside every other manager you run in one table, mpm upgrade --all updates them together, and mpm sbom exports the whole machine as one bill of materials.

Every mpm command also gains --dry-run and --plan previews, cross-scheme version comparison and purl identifiers. See manager augmentations for how each one is built.

Your cpan commands, in mpm

You already know cpan: each operation maps one-to-one onto mpm, in an interface shared by every manager.

To…

With cpan

With mpm

List what’s installed

cpan -l

mpm --cpan installed

List outdated packages

cpan -O

mpm --cpan outdated

Install a package

cpan Try::Tiny

mpm install pkg:cpan/Try::Tiny

Upgrade one package

cpan -i Try::Tiny

mpm --cpan upgrade Try::Tiny

Upgrade everything

cpan -u

mpm --cpan upgrade --all

Prefix any command above with --dry-run to simulate the underlying manager calls without touching the system: the safe way to watch what mpm would do before trusting it.

Operations

Operation

Supported

Notes

installed

✅

outdated

✅

orphans

search

install

✅

upgrade

✅

upgrade_all

✅

remove

❌

CPAN’s client cannot uninstall a module at all.

sync

cleanup

doctor

Configuration

  • Ignore cpan on the mpm CLI by passing the --no-cpan option.

  • Ignore it for every run in your configuration:

    [mpm]
cpan = false

  • Raise the timeout of all cpan calls:

    [mpm.overrides.cpan]
timeout = 900

  • Run mpm config-template cpan to print all overridable settings for your configuration file:

    [mpm.overrides.cpan]
cli_names = [
    "cpan",
]
cli_search_path = []
dry_run = false
ignore_auto_updates = true
plan = false
post_args = []
pre_args = []
pre_cmds = []
requirement = ">=1.64"
stop_on_error = false
unmaintained = false
version_cli_options = [
    "-v",
]
version_regexes = [
    "CPAN\\.pm\\s+version\\s+(?P<version>\\S+)",
]

[mpm.overrides.cpan.extra_env]
PERL_MM_USE_DEFAULT = "1"

The arguments and environment variables listed in the box atop this page are forced on every cpan call, so runs stay quiet, non-interactive and reproducible: the defaults you would set in CI anyway.

Recipes

A few jobs you would otherwise script around cpan, one mpm command each:

  • Snapshot and clone a machine: mpm --cpan dump cpan.toml, then mpm restore cpan.toml on the next one.

  • Export a compliance SBOM: mpm --cpan sbom (CycloneDX by default, --spdx for SPDX).

Privilege escalation

mpm runs this manager as the current user and never prepends sudo by default. Flip the policy for its privileged operations with --sudo or the per-manager sudo override.

Its privileged operations are install, upgrade, upgrade_all.

See privilege escalation for the full policy.

Cooldown

State of Perl CPAN’s release-age gating, from the cooldown support table:

Status: ❌ None

A cooldown only pays off where a compromised release can be withdrawn while the clock runs, and can only be emulated where the registry dates its releases. From the retraction table:

  • Registry: CPAN / PAUSE (pkg:cpan)

  • Retraction: Unpublish: an author can delete a distribution from the mirrors, though “a secondary mirror network called BackPAN retains distributions even if they are deleted from CPAN” (CPAN)

With --cooldown set, mpm skips this manager’s install and upgrade operations rather than run them unguarded (fail-closed); --cooldown best-effort opts back in.

Reference traces

A collection of raw native outputs captured from the manager’s own CLI and recorded in the manager source. If you know Perl CPAN well and a transcript below looks wrong, or a newer release changed its output format, report it.

$ cpan -l
Loading internal logger. Log::Log4perl recommended for better logging
Glib	1.3294
Cairo	1.109
Clone	0.47
Text::CharWidth	0.04
Text::Iconv	1.7
HTML::TokeParser	3.83
HTML::PullParser	3.83
HTML::Entities	3.83
HTML::Parser	3.83
HTML::LinkExtor	3.83
HTML::Filter	3.83
HTML::HeadParser	3.83
Net::SSLeay	1.94
Net::DBus	1.2.0
Net::DBus::Error	undef
Net::DBus::Callback	undef
Net::DBus::Reactor	undef

$ cpan -O
Loading internal logger. Log::Log4perl recommended for better logging
Reading '/home/user/.cpan/Metadata'
  Database was generated on Wed, 16 Sep 2026 14:17:02 GMT
Module Name                                Local    CPAN
-------------------------------------------------------------------------
App::Cpan                                 1.6780  1.6790
App::Prove                                3.4800  3.5200
App::Prove::State                         3.4800  3.5200
App::Prove::State::Result                 3.4800  3.5200
App::Prove::State::Result::Test           3.4800  3.5200
Archive::Tar                              3.0200  3.1200
Archive::Tar::Constant                    3.0200  3.1200

Version check

The version is probed by running:

$ cpan -v
Loading internal logger. Log::Log4perl recommended for better logging
>(info): /usr/bin/cpan script version 1.678, CPAN.pm version 2.36

and extracted with:

r"CPAN\.pm\s+version\s+(?P<version>\S+)"

Upstream project

Metrics

andk/cpanpm

Activity

commit activity open issues open pull requests

Popularity

forks watchers contributors

Metadata

latest tag license main language

Changelog

  • 8.0.0 (2026-09-20)

    • Warn with the [mpm.overrides.<id>] sudo = true remedy when an operation carrying a dormant privileged marker fails on a permission error, like a global install into a root-owned prefix.

    • Stop reading cpan’s index-refresh progress lines as packages, and list the core modules Debian and Ubuntu reach through symlinked @INC directories, which cpan -l skips.

  • 7.4.1 (2026-07-28)

    • Document why cpan reports Perl’s core modules as outdated while upgrade --all never upgrades them: their versions are tied to the running Perl, cleared only by a writable Perl earlier on PATH. Addresses #1983.

  • 7.4.0 (2026-07-25)

    • The write operations carry dormant privileged markers like pip and npm: --sudo or a per-manager sudo = true override escalates installs into a system Perl or Ruby. Nothing escalates by default.

  • 6.3.0 (2026-04-09)

    • Add CPAN package manager for Perl modules with installed, outdated, install, and upgrade support. Closes #602.