---

name: perl-cpan-ecosystem description: This skill should be used when the user asks to install Perl modules, use cpanm, create a cpanfile, manage Perl dependencies, set up Carton, configure local lib, or mentions CPAN, cpanminus, module installation, or Perl package management.

CPAN Ecosystem Guide

Comprehensive guide for managing Perl modules using cpanm, cpanfile, Carton, and local::lib.

cpanm (cpanminus)

The recommended tool for installing CPAN modules.

Installation

# Using curl
curl -L https://cpanmin.us | perl - --self-upgrade

# Using system package manager
# Debian/Ubuntu
sudo apt install cpanminus

# macOS
brew install cpanminus

# From CPAN
cpan App::cpanminus

Basic Usage

# Install a module
cpanm Module::Name

# Install specific version
cpanm Module::Name@1.23

# Install with dependencies only (for testing)
cpanm --installdeps .

# Quiet installation
cpanm --quiet --notest Module::Name

# Install to local directory
cpanm --local-lib=~/perl5 Module::Name

Common Flags

Flag	Purpose
--notest	Skip tests (faster, less safe)
--quiet	Minimal output
--verbose	Detailed output
--force	Install despite test failures
--installdeps	Install dependencies only
--local-lib=DIR	Install to specific directory
--self-upgrade	Update cpanm itself
--mirror URL	Use specific CPAN mirror
--skip-satisfied	Skip already installed

Mirror Configuration

# Use a specific mirror
cpanm --mirror https://cpan.metacpan.org Module::Name

# Use mirror only (no fallback)
cpanm --mirror https://cpan.metacpan.org --mirror-only Module::Name

cpanfile

Declare dependencies in a cpanfile for reproducible installations.

Basic cpanfile

# cpanfile
requires 'Moo';
requires 'Path::Tiny';
requires 'Try::Tiny';

# Version constraints
requires 'DBI', '1.643';           # Exact version
requires 'JSON::XS', '>= 4.0';     # Minimum version
requires 'Plack', '< 2.0';         # Maximum version
requires 'Moose', '>= 2.0, < 3.0'; # Range

# Development dependencies
on 'develop' => sub {
    requires 'Perl::Critic';
    requires 'Perl::Tidy';
};

# Test dependencies
on 'test' => sub {
    requires 'Test::More', '0.98';
    requires 'Test::Exception';
    requires 'Test::Deep';
};

# Build dependencies
on 'build' => sub {
    requires 'Module::Build';
};

# Recommended (not required)
recommends 'JSON::XS';
suggests 'IO::Socket::SSL';

Feature Phases

Phase	Purpose	When Installed
runtime	Production deps	Always (default)
test	Testing deps	--with-test
develop	Dev tools	--with-develop
build	Build tools	During build

Install from cpanfile

# Install all runtime dependencies
cpanm --installdeps .

# Include test dependencies
cpanm --installdeps --with-test .

# Include all phases
cpanm --installdeps --with-develop --with-test .

Carton

Lock dependencies to exact versions for reproducible deployments.

Installation

cpanm Carton

Basic Workflow

# Create cpanfile.snapshot from cpanfile
carton install

# Install to local/ directory
carton install --deployment

# Update dependencies
carton update

# Run script with locked dependencies
carton exec perl script.pl

# Run with specific local path
carton exec --path local perl app.pl

Generated Files

File	Purpose	Git
cpanfile	Dependency declaration	Commit
cpanfile.snapshot	Locked versions	Commit
local/	Installed modules	Ignore

.gitignore for Carton

/local/
/.carton/

Deployment Pattern

# Development machine
carton install
git add cpanfile cpanfile.snapshot
git commit -m "Update dependencies"

# Production machine
git pull
carton install --deployment --without develop,test
carton exec perl app.pl

local::lib

Install modules in user directory without root access.

Setup

# Install local::lib
cpanm local::lib

# Initialize (add to shell profile)
eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)

# Add to ~/.bashrc or ~/.zshrc
echo 'eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)' >> ~/.bashrc

Environment Variables

local::lib sets these variables:

PERL5LIB=$HOME/perl5/lib/perl5
PERL_LOCAL_LIB_ROOT=$HOME/perl5
PERL_MB_OPT="--install_base $HOME/perl5"
PERL_MM_OPT="INSTALL_BASE=$HOME/perl5"
PATH=$HOME/perl5/bin:$PATH

Custom Installation Path

# Use different directory
eval $(perl -Mlocal::lib=$HOME/myperllib)

# Project-specific
eval $(perl -Mlocal::lib=./local)

Module Resolution Order

Perl searches for modules in this order:

1. Directories in @INC
2. PERL5LIB paths
3. Site lib (system-wide)
4. Core modules

Check current @INC:

perl -V  # Full config including @INC
perl -e 'print join("\n", @INC)'

Finding Modules

Search MetaCPAN

# Using mccpan (if installed)
cpanm App::cpanminus::reporter
cpan-outdated

# Or use web: https://metacpan.org/

Check Installed Modules

# List all installed
perldoc perllocal

# Check specific module
perl -MModule::Name -e 'print $Module::Name::VERSION'

# Using cpan
cpan -l

# Using pmvers (from pmtools)
pmvers Module::Name

Troubleshooting

Common Issues

Module not found after install:

# Check PERL5LIB
echo $PERL5LIB

# Verify module location
perl -MModule::Name -e 'print $INC{"Module/Name.pm"}'

Permission denied:

# Use local::lib instead of sudo
eval $(perl -Mlocal::lib)
cpanm Module::Name

Build failures:

# Install build tools
# Debian/Ubuntu
sudo apt install build-essential

# Check build log
less ~/.cpanm/build.log

XS module compilation:

# Install development headers
sudo apt install libssl-dev  # For SSL modules
sudo apt install libxml2-dev # For XML modules

Project Setup Example

Initialize a new Perl project with proper dependency management:

# Create project structure
mkdir -p myapp/{lib,t,bin}
cd myapp

# Create cpanfile
cat > cpanfile << 'EOF'
requires 'Moo';
requires 'Path::Tiny';
requires 'Try::Tiny';

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

# Install with Carton
carton install

# Add to .gitignore
echo '/local/' >> .gitignore
echo '/.carton/' >> .gitignore

# Commit dependency spec
git add cpanfile cpanfile.snapshot

Additional Resources

For Perl version management with perlbrew, see the perl-environment-setup skill.