App::cp...atscript(3)

📦
version 1.7048 · 7 versions
, in opensuse-leap 16.0

okay so bestie, welcome to App::cp...atscript(3) — straight outta the User Contributed Perl Documentation section of the manual, and it's literally the whole cpanm era. buckle up, we're getting your modules together 💅✨

🌸 NAME 🌸

cpanm — get, unpack build and install modules from CPAN. that's the whole vibe, bestie. it fetches, unpacks, builds and installs. slay 🎀

✨ SYNOPSIS ✨

okay so here's the whole mood board of what you can throw at it:

cpanm Test::More                                 # install Test::More
cpanm MIYAGAWA/Plack-0.99_05.tar.gz              # full distribution path
cpanm http://example.org/LDS/CGI.pm-3.20.tar.gz  # install from URL
cpanm ~/dists/MyCompany-Enterprise-1.00.tar.gz   # install from a local file
cpanm --interactive Task::Kensho                 # Configure interactively
cpanm .                                          # install from local directory
cpanm --installdeps .                            # install all the deps for the current directory
cpanm -L extlib Plack                            # install Plack and all non-core deps into extlib
cpanm --mirror http://cpan.cpantesters.org/ DBI  # use the fast-syncing mirror
cpanm --from https://cpan.metacpan.org/ Plack    # use only the HTTPS mirror

like, every one of those is a real thing you can just type. iykyk 🦋

🎀 COMMANDS 🎀

📦 (arguments) 📦

so the bare arguments you pass? they can be a module name, a distribution file, a local file path, an HTTP URL or a git repository URL — and honestly all of these just work exactly how your little heart expects. no cap:

cpanm Plack
cpanm Plack/Request.pm
cpanm MIYAGAWA/Plack-1.0000.tar.gz
cpanm /path/to/Plack-1.0000.tar.gz
cpanm http://cpan.metacpan.org/authors/id/M/MI/MIYAGAWA/Plack-0.9990.tar.gz
cpanm git://github.com/plack/Plack.git

and here's the part where it gets iconic — you can use the ~ and @ notation to pin down a version for a given module. ~ gives you the version requirement in the CPAN::Meta::Spec format, while @ pins the exact version and is basically a shortcut for ~"== VERSION". periodt:

cpanm Plack~1.0000                 # 1.0000 or later
cpanm Plack~">= 1.0000, < 2.0000"  # latest of 1.xxxx
cpanm Plack@0.9990                 # specific version. same as Plack~"== 0.9990"

that version query — whether it's a specific version or a range — gets sent to MetaCPAN to search for previous releases. and it searches for BackPAN archives by default, UNLESS you pass the --dev option, in which case archived versions get filtered out. okay go off 🔥

for a git repository you can also specify a branch, tag, or commit SHA to build. the default is master:

cpanm git://github.com/plack/Plack.git@1.0000        # tag
cpanm git://github.com/plack/Plack.git@devel         # branch

the rest of the commands

  • -i, --install — installs the modules. it's the default behavior anyway, so this is really just a compatibility option to make it behave like cpan or cpanp. legacy-core, honestly 💜
  • --self-upgrade — upgrades itself. it's just an alias for cpanm App::cpanminus. self-care, literally ✨
  • --info — displays the distribution information in AUTHOR/Dist-Name-ver.tar.gz format in the standard out. just the tea, no installing 🍓
  • --installdeps — installs the dependencies of the target distribution but won't build the thing itself. super handy if you wanna try out an application from a version controlled repository such as git:
cpanm --installdeps .
  • --look — downloads and unpacks the distribution and then opens the directory with your shell. handy for poking around the source code or doing manual testing like a little detective 🧚
  • -h, --help — displays the help message.
  • -V, --version — displays the version number.

💅 OPTIONS 💅

okay so hear me out — you can specify the default options in the PERL_CPANM_OPT environment variable. set it once, live your life 🫶

  • -f, --force — force install modules even when testing failed. bold. reckless. sometimes necessary 💀
  • -n, --notest — skips the testing of modules. use this only when you just want to save time installing hundreds of distributions to the same perl and architecture you've already tested to make sure it builds fine. don't be chaotic about it. defaults to false, and you can say --no-notest to override when it's set in the default options in PERL_CPANM_OPT.
  • --test-only — runs the tests only, and does not install the specified module or distributions. handy if you want to verify that new (or even old) releases pass their unit tests without installing the module. note that if you specify this option with a module or distribution that has dependencies, those dependencies will get installed if you don't currently have them. so like, "test only" but not that test only, yk? 🙈
  • -S, --sudo — switches to the root user with sudo when installing modules. use this if you want to install modules to the system perl include path. defaults to false, and you can say --no-sudo to override when it's set in the default options in PERL_CPANM_OPT.
  • -v, --verbose — makes the output verbose. it also enables the interactive configuration. (see --interactive). she's chatty and she's proud 👑
  • -q, --quiet — makes the output even more quiet than the default. it only shows the successful/failed dependencies to the output. lowkey mode activated 🤫
  • -l, --local-lib — sets the local::lib compatible path to install modules to. you don't need to set this if you already configured the shell environment variables using local::lib, but this can be used to override that as well. options, bestie 💖
  • -L, --local-lib-contained — same as --local-lib but with --self-contained set. all non-core dependencies will be installed even if they're already installed.

for instance,

cpanm -L extlib Plack

would install Plack and all of its non-core dependencies into the directory extlib, which can be loaded from your application with:

use local::lib '/path/to/extlib';
⚠️ note that this option does NOT reliably work with perl installations supplied by operating system vendors that strips standard modules from perl, such as RHEL, Fedora and CentOS, UNLESS you also install packages supplying all the modules that have been stripped. for these systems you will probably want to install the perl-core meta-package which does just that. no cap, read that twice 😭
  • --self-contained — when examining the dependencies, assume no non-core modules are installed on the system. handy if you want to bundle application dependencies in one directory so you can distribute to other machines. little self-sufficient queen 🎀
  • --exclude-vendor — don't include modules installed under the 'vendor' paths when searching for core modules when the --self-contained flag is in effect. this restores the behaviour from before version 1.7023. vintage behaviour, retro vibes 🌈
  • --mirror — specifies the base URL for the CPAN mirror to use, such as http://cpan.cpantesters.org/ (you can omit the trailing slash). you can specify multiple mirror URLs by repeating the command line option.

you can use a local directory that has a CPAN mirror structure (created by tools such as OrePAN or Pinto) by using a special URL scheme file://. if the given URL begins with / (without any scheme), it is considered as a file scheme as well.

cpanm --mirror file:///path/to/mirror
cpanm --mirror ~/minicpan      # Because shell expands ~ to /home/user

defaults to http://www.cpan.org/. the og 💅

  • --mirror-only — downloads the mirror's 02packages.details.txt.gz index file instead of querying the CPAN Meta DB. this will also effectively opt out of sending your local perl versions to backend database servers such as CPAN Meta DB and MetaCPAN.

select this option if you are using a local mirror of CPAN, such as minicpan when you're offline, or your own CPAN index (a.k.a darkpan). offline girlies rise 🦋

  • --from, -M
cpanm -M https://cpan.metacpan.org/
cpanm --from https://cpan.metacpan.org/

use the given mirror URL and its index as the only source to search and download modules from.

it works similar to --mirror and --mirror-only combined, with a small difference: unlike --mirror which appends the URL to the list of mirrors, --from (or -M for short) uses the specified URL as its only source to download index and modules from. this makes the option always override the default mirror, which might have been set via global options such as the one set by the PERL_CPANM_OPT environment variable. main character energy — it does not share the spotlight ✨

tip: it might be useful if you name these options with your shell aliases, like: alias minicpanm='cpanm --from ~/minicpan' alias darkpan='cpanm --from http://mycompany.example.com/DPAN'
  • --mirror-index — EXPERIMENTAL: specifies the file path to 02packages.details.txt for the module search index.
  • --cpanmetadb — EXPERIMENTAL: specifies an alternate URI for CPAN MetaDB index lookups.
  • --metacpan — prefers MetaCPAN API over CPAN MetaDB.
  • --cpanfile — EXPERIMENTAL: specifies an alternate path for cpanfile to search for, when the --installdeps command is in use. defaults to cpanfile.
  • --prompt — prompts when a test fails so that you can skip, force install, retry or look in the shell to see what's going wrong. it also prompts when one of the dependencies failed, if you want to proceed with the installation. defaults to false, and you can say --no-prompt to override if it's set in the default options in PERL_CPANM_OPT. it's literally checking in on you 🫶
  • --dev — EXPERIMENTAL: search for a newer developer release as well. defaults to false.
  • --reinstall — okay so cpanm, when given a module name in the command line (i.e. cpanm Plack), checks the locally installed version first and skips if it is already installed. this option makes it skip that check, so:
cpanm --reinstall Plack

would reinstall Plack even if your locally installed version is latest, or even newer (which would happen if you install a developer release from version control repositories).

defaults to false. sometimes you just want a fresh start, yk? 🔥

  • --interactive — makes the configuration (such as Makefile.PL and Build.PL) interactive, so you can answer questions in the distribution that requires custom configuration or Task:: distributions. defaults to false, and you can say --no-interactive to override when it's set in the default options in PERL_CPANM_OPT.
  • --pp, --pureperl — prefer Pure perl build of modules by setting PUREPERL_ONLY=1 for MakeMaker and --pureperl-only for Build.PL based distributions. note that not all of the CPAN modules support this convention yet. pure vibes only, when it works 🧚
  • --with-recommends, --with-suggests — EXPERIMENTAL: installs dependencies declared as recommends and suggests respectively, per META spec. when these dependencies fail to install, cpanm continues the installation, since they're just recommendation/suggestion.
⚠️ enabling this could potentially make a circular dependency for a few modules on CPAN, when recommends adds a module that recommends back the module in return. it's giving mutuals who keep recommending each other 😭💀
  • --without-recommend, --without-suggests — the override squad 🫶 these let you flip the default decision that got made earlier up in PERL_CPANM_OPT. Both default to false, no cap.
  • --with-develop — EXPERIMENTAL, bestie, don't @ me 🙈 installs develop phase dependencies from META files or cpanfile when you use it with --installdeps. Defaults to false.
  • --with-configure — also EXPERIMENTAL ✨ installs configure phase dependencies from cpanfile when you pair it with --installdeps. Defaults to false.
  • --with-feature, --without-feature, --with-all-features — EXPERIMENTAL 💅 picks the feature to enable, if a module supports optional features per META spec 2.0.
cpanm --with-feature=opt_csv Spreadsheet::Read

the features can also be interactively chosen when --interactive option is enabled. --with-all-features enables all the optional features, and --without-feature can select a feature to disable. iykyk 🌸

  • --configure-timeout, --build-timeout, --test-timeout — how long (in seconds) to wait for the configure, build and test process. Current default values are: 60 for configure, 3600 for build and 1800 for test. it's giving patience 💀
  • --configure-args, --build-args, --test-args, --install-args — EXPERIMENTAL 🔥 passes arguments for configure/build/test/install commands respectively, for a given module to install.
cpanm DBD::mysql --configure-args="--cflags=... --libs=..."

the argument is only enabled for the module passed as a command line argument, not dependencies. so it's a very exclusive invite-only situation 💅

  • --scandeps — DEPRECATED ⚠️ scans the depencencies of given modules and outputs the tree in a text format. (See --format below for more options.)

because this command doesn't actually install any distributions, it will be useful that by typing:

cpanm --scandeps Catalyst::Runtime

you can make sure what modules will be installed. literally the vibe check before the commit ✨

this command takes into account which modules you already have installed in your system. If you want to see what modules will be installed against a vanilla perl installation, you might want to combine it with -L option.

  • --format — DEPRECATED ⚠️ determines what format to display the scanned dependency tree. Available options are tree, json, yaml and dists.
    • tree — displays the tree in a plain text format. This is the default value. 👑
    • json, yaml — outputs the tree in a JSON or YAML format. JSON and YAML modules need to be installed respectively. The output tree is represented as a recursive tuple of:
[ distribution, dependencies ]

and the container is an array containing the root elements. Note that there may be multiple root nodes, since you can give multiple modules to the --scandeps command. lowkey tree-shaped and proud of it 🌈

  • dists — dists is a special output format, where it prints the distribution filename in the depth first order after the dependency resolution, like:
GAAS/MIME-Base64-3.13.tar.gz
GAAS/URI-1.58.tar.gz
PETDANCE/HTML-Tagset-3.20.tar.gz
GAAS/HTML-Parser-3.68.tar.gz
GAAS/libwww-perl-5.837.tar.gz

which means you can install these distributions in this order without extra dependencies. When combined with -L option, it will be useful to replay installations on other machines. obsessed with a reproducible order fr fr 🎀

  • --save-dists — specifies the optional directory path to copy downloaded tarballs in the CPAN mirror compatible directory structure i.e. authors/id/A/AU/AUTHORS/Foo-Bar-version.tar.gz

if the distro tarball did not come from CPAN, for example from a local file or from GitHub, then it will be saved under vendor/Foo-Bar-version.tar.gz. either way it's getting a home 💖

  • --uninst-shadows — uninstalls the shadow files of the distribution that you're installing. This eliminates the confusion if you're trying to install core (dual-life) modules from CPAN against perl 5.10 or older, or modules that used to be XS-based but switched to pure perl at some version.

if you run cpanm as root and use INSTALL_BASE or equivalent to specify custom installation path, you SHOULD disable this option so you won't accidentally uninstall dual-life modules from the core include path. seriously bestie, read that twice 😭

defaults to true if your perl version is smaller than 5.12, and you can disable that with --no-uninst-shadows.

NOTE: 🚨 Since version 1.3000 this flag is turned off by default for perl newer than 5.12, since with 5.12 @INC contains site_perl directory before the perl core library path, and uninstalling shadows is not necessary anymore and does more harm by deleting files from the core library path. so like… don't touch it 💀
  • --uninstall, -U — uninstalls a module from the library path. It finds a packlist for given modules, and removes all the files included in the same distribution. the full clean-girl exit 🧹✨

if you enable local::lib, it only removes files from the local::lib directory.

if you try to uninstall a module in perl directory (i.e. core module), an error will be thrown. it said nope 🙈

a dialog will be prompted to confirm the files to be deleted. If you pass -f option as well, the dialog will be skipped and uninstallation will be forced. so like, careful with -f, that's main character energy with zero safety net 🔥

  • --cascade-search — EXPERIMENTAL ⭐ specifies whether to cascade search when you specify multiple mirrors and a mirror doesn't have a module or has a lower version of the module than requested. Defaults to false. fallback queens stay winning 💅
  • --skip-installed — specifies whether a module given in the command line is skipped if its latest version is already installed. Defaults to true.
NOTE: the PERL5LIB environment variable have to be correctly set for this to work with modules installed using local::lib, unless you always use the -l option. set it right or it's not gonna vibe check correctly 🫶
  • --skip-satisfied — EXPERIMENTAL ✨ specifies whether a module (and version) given in the command line is skipped if it's already installed.

if you run:

cpanm --skip-satisfied CGI DBI~1.2

cpanm won't install them if you already have CGI (for whatever versions) or have DBI with version higher than 1.2. It is similar to --skip-installed but while --skip-installed checks if the latest version of CPAN is installed, --skip-satisfied checks if a requested version (or not, which means any version) is installed. subtle but iconic difference 👑

defaults to false.

  • --verify — verify the integrity of distribution files retrieved from CPAN using CHECKSUMS file, and SIGNATURES file (if found in the distribution). Defaults to false.
using this option does not verify the integrity of the CHECKSUMS file, and it's unsafe to rely on this option if you're using a CPAN mirror that you do not trust. ok so this one's a real one, no jokes 😭🚨
  • --report-perl-version — whether it reports the locally installed perl version to the various web server as part of User-Agent. Defaults to true unless CI related environment variables such as TRAVIS, CI or AUTOMATED_TESTING is enabled. You can disable it by using --no-report-perl-version. letting them know what perl you're on, very transparent of you 💅
  • --auto-cleanup — specifies the number of days in which cpanm's work directories expire. Defaults to 7, which means old work directories will be cleaned up in one week. 🧹

you can set the value to 0 to make cpan never cleanup those directories. (yes that's a long-term commitment lol)

  • --man-pages — generates man pages for executables (man1) and libraries (man3).

defaults to true (man pages generated) unless -L|--local-lib-contained option is supplied in which case it's set to false. You can disable it with --no-man-pages. docs are cute 🎀

  • --lwp — uses LWP module to download stuff over HTTP. Defaults to true, and you can say --no-lwp to disable using LWP, when you want to upgrade LWP from CPAN on some broken perl systems. sometimes you gotta disable the downloader to download the downloader, iykyk 💀
  • --wget — uses GNU Wget (if available) to download stuff. Defaults to true, and you can say --no-wget to disable using Wget (versions of Wget older than 1.9 don't support the --retry-connrefused option used by cpanm). old wget is not invited to the party 🙈
  • --curl — uses cURL (if available) to download stuff. Defaults to true, and you can say --no-curl to disable using cURL.

normally with --lwp, --wget and --curl options set to true (which is the default) cpanm tries LWP, Wget, cURL and HTTP::Tiny (in that order) and uses the first one available. it's giving audition lineup and the first one to show up gets the role ⭐

🌸 ENVIRONMENT VARIABLES 🌸

  • PERL_CPANM_HOME — the directory cpanm should use to store downloads and build and test modules. Defaults to the .cpanm directory in your user's home directory. yes it lives in your home, it's family 🫶
  • PERL_CPANM_OPT — if set, adds a set of default options to every cpanm command. These options come first, and so are overridden by command-line options. defaults with main character energy, command line always wins 👑

🦋 SEE ALSO 🦋

  • App::cpanminus — the actual whole entire thing bestie, go read it 💖

Copyright 2010- Tatsuhiko Miyagawa.

👑 AUTHOR 👑

Tatsuhiko Miyagawa

and that's the whole page, periodt ✨ this rendered from perl v5.42.0 on 2024-12-12 (the docs themselves literally signed and dated, iconic of them 💅). go install something cute, bestie 🍓💜

📦 where this page comes from