Perl CPAN¶

ID: cpan
Home page: https://www.cpan.org
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: meta_package_manager/managers/cpan.toml

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. cpan cannot uninstall a module, so no remove operation is declared.

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 <package_id>`	`mpm install pkg:cpan/<package_id>`
Upgrade one package	`cpan -i <package_id>`	`mpm --cpan upgrade <package_id>`
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
`installed`	✓
`outdated`	✓
`orphans`
`search`
`install`	✓
`upgrade`	✓
`upgrade_all`	✓
`remove`
`sync`
`cleanup`
`doctor`

Selecting and configuring `cpan`¶

Deselect cpan for a single run with --no-cpan, or persist the choice in your configuration:

[mpm]
cpan = false

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.

Keep it enabled but tune how mpm drives it with a per-manager override:

[mpm.managers.cpan]
timeout = 900

mpm config-template cpan prints every overridable attribute as a ready-to-paste block.

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.

Root is required for its install, upgrade, upgrade_all operations.

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); --allow-unsupported-managers opts back in.

Version probe¶

The version is probed by running:

$ cpan -v
>(info): /usr/bin/cpan script version 1.676, CPAN.pm version 2.28

and extracted with:

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

Reference traces¶

Raw native outputs captured in the bundled definition: the reference mpm’s parsers were written against. 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
O	1.03
Errno	1.33
Encode	3.08_01
meta_notation	undef

$ cpan -O
Loading internal logger. Log::Log4perl recommended for better logging
Reading '/Users/kde/.cpan/Metadata'
  Database was generated on Thu, 26 Mar 2026 13:41:03 GMT
Module Name                                Local    CPAN
---------------------------------------------------------------
Algorithm::C3                             0.1000  0.1100
Archive::Tar                              2.3800  3.0400

Feed any of these through mpm and the raw output becomes one uniform table, the same shape for every manager: filter it, project columns, or export it (mpm --cpan installed --output json, or csv, toml, yaml), each package carrying a purl and a version comparable across managers.

Changelog¶

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.