Help us improve
Share bugs, ideas, or general feedback.
From perl-development
Guides Perl dependency management: install modules with cpanm (flags, mirrors, local-lib), declare deps in cpanfile (phases, versions), use Carton/local::lib.
npx claudepluginhub jamie-bitflight/claude_skills --plugin perl-developmentHow this skill is triggered — by the user, by Claude, or both
Slash command
/perl-development:perl-cpan-ecosystemThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Comprehensive guide for managing Perl modules using cpanm, cpanfile, Carton, and local::lib.
Sets up Perl environments with perlbrew: install/switch versions, manage installations, create isolated libraries without root access.
Provides modern Perl 5.36+ idioms, best practices, and conventions for writing robust, maintainable Perl applications. Covers pragmas, signatures, context sensitivity, postfix dereferencing, and error handling.
Provides modern Perl 5.36+ idioms, best practices, and conventions for writing robust, maintainable Perl applications. Covers signatures, error handling, Moo OOP, and more.
Share bugs, ideas, or general feedback.
Comprehensive guide for managing Perl modules using cpanm, cpanfile, Carton, and local::lib.
The recommended tool for installing CPAN modules.
# 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
# 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
| 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 |
# 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
Declare dependencies in a cpanfile for reproducible installations.
# 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';
| 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 all runtime dependencies
cpanm --installdeps .
# Include test dependencies
cpanm --installdeps --with-test .
# Include all phases
cpanm --installdeps --with-develop --with-test .
Lock dependencies to exact versions for reproducible deployments.
cpanm Carton
# 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
| File | Purpose | Git |
|---|---|---|
cpanfile | Dependency declaration | Commit |
cpanfile.snapshot | Locked versions | Commit |
local/ | Installed modules | Ignore |
/local/
/.carton/
# 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
Install modules in user directory without root access.
# 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
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
# Use different directory
eval $(perl -Mlocal::lib=$HOME/myperllib)
# Project-specific
eval $(perl -Mlocal::lib=./local)
Perl searches for modules in this order:
@INCPERL5LIB pathsCheck current @INC:
perl -V # Full config including @INC
perl -e 'print join("\n", @INC)'
# Using mccpan (if installed)
cpanm App::cpanminus::reporter
cpan-outdated
# Or use web: https://metacpan.org/
# 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
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
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
For Perl version management with perlbrew, see the perl-environment-setup skill.