CPANMS(1)

📦 version 1.7048, in alpine 3.24

🎀 cpanms(1) — get, unpack build and install modules from CPAN via HTTPS 🎀

🌸 NAME 🌸

Okay bestie, this is the manual for cpanms, and its whole personality is: get, unpack build and install modules from CPAN via HTTPS. That’s the gig. ✨

✨ SYNOPSIS ✨

Like, here’s the group chat of “what does this actually look like”:

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

🛠 MODIFICATIONS 🛠

So this version of cpanminus has been modified in the following 3 ways — yes, exactly 3, we’re not being mysterious:

  1. The --retry-connrefused option for the wget backend has been commented out. This restores compatibility with Busybox wget that comes pre-installed in the Alpine base system.
  2. The default CPAN mirrors have been changed from HTTP to HTTPS. This provides better security. Alpine's apk package manager ensures that the necessary dependencies for enabling HTTPS support with Busybox wget are installed with this package.
  3. The has_working_lwp method has been altered to first check if @$mirrors provided to it as an argument is an empty array. This causes $https to be true when @$mirrors is empty, which is the behavior we want, because the default mirrors have been switched to HTTPS as stated above in (2). When $https is true, the eval-require check for LWP::Protocol::https runs, so if you don't have that installed, this version of cpanminus will fallback on wget, instead of displaying the "LWP will support https URLs if the LWP::Protocol::https module is installed" error message.

If you're looking for the unmodified cpanminus, please install the perl-app-cpanminus package instead. 💖

💬 COMMANDS 💬

🫶 (arguments) 🫶

Command line arguments can be either a module name, distribution file, local file path, HTTP URL or git repository URL. Following commands will all work as you expect — no cap:

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

Additionally, you can use the notation using ~ and @ to specify version for a given module. ~ specifies the version requirement in the CPAN::Meta::Spec format, while @ pins the exact version, and is a shortcut for ~"== VERSION". Obsessed with the precision, honestly:

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

The version query including specific version or range will be sent to MetaCPAN to search for previous releases. The query will search for BackPAN archives by default, unless you specify --dev option, in which case, archived versions will be filtered out.

For a git repository, you can specify a branch, tag, or commit SHA to build. The default is master — main character energy, but make it git:

cpanms git://github.com/plack/Plack.git@1.0000        # tag
cpanms git://github.com/plack/Plack.git@devel         # branch
  • -i, --install — Installs the modules. This is a default behavior and this is just a compatibility option to make it work like cpan or cpanp. 💅
  • --self-upgrade — Upgrades itself. It's just an alias for:
cpanms App::cpanminus
  • --info — Displays the distribution information in AUTHOR/Dist-Name-ver.tar.gz format in the standard out.
  • --installdeps — Installs the dependencies of the target distribution but won't build itself. Handy if you want to try the application from a version controlled repository such as git.
cpanms --installdeps .
  • --look — Download and unpack the distribution and then open the directory with your shell. Handy to poke around the source code or do manual testing.
  • -h, --help — Displays the help message.
  • -V, --version — Displays the version number.

🌈 OPTIONS 🌈

You can specify the default options in PERL_CPANM_OPT environment variable. Set it once, vibe forever. ✨

  • -f, --force — Force install modules even when testing failed. Bold. Slightly chaotic. Sometimes necessary.
  • -n, --notest — Skip the testing of modules. Use this only when you just want to save time for installing hundreds of distributions to the same perl and architecture you've already tested to make sure it builds fine.

Defaults to false, and you can say --no-notest to override when it is set in the default options in PERL_CPANM_OPT.

  • --test-only — Run the tests only, and do not install the specified module or distributions. Handy if you want to verify the new (or even old) releases pass its unit tests without installing the module.

Note that if you specify this option with a module or distribution that has dependencies, these dependencies will be installed if you don't currently have them.

  • -S, --sudo — Switch 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 is set in the default options in PERL_CPANM_OPT.

  • -v, --verbose — Makes the output verbose. It also enables the interactive configuration. (See --interactive)
  • -q, --quiet — Makes the output even more quiet than the default. It only shows the successful/failed dependencies to the output.
  • -l, --local-lib — Sets the local::lib compatible path to install modules to. You don't need to set this if you already configure the shell environment variables using local::lib, but this can be used to override that as well.
  • -L, --local-lib-contained — Same with --local-lib but with --self-contained set. All non-core dependencies will be installed even if they're already installed.

For instance,

cpanms -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. 🫶

  • --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.
  • --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.
  • --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.

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

Defaults to http://www.cpan.org/.

  • --mirror-only — Download the mirror's 02packages.details.txt.gz index file instead of querying the CPAN Meta DB. This will also effectively opt out 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).

  • --from, -M —
cpanms -M https://cpan.metacpan.org/
cpanms --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 PERL_CPANM_OPT environment variable.

Tip: It might be useful if you name these options with your shell aliases, like:

alias minicpanm='cpanms --from ~/minicpan'
alias darkpan='cpanms --from http://mycompany.example.com/DPAN'
  • --mirror-index — EXPERIMENTAL: Specifies the file path to 02packages.details.txt for 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 --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 dependency failed if you want to proceed 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.

  • --dev — EXPERIMENTAL: search for a newer developer release as well. Defaults to false.
  • --reinstall — cpanms, when given a module name in the command line (i.e. cpanms Plack), checks the locally installed version first and skips if it is already installed. This option makes it skip the check, so:
cpanms --reinstall Plack

...would reinstall Plack even if your locally installed version is latest, or even newer — which, yeah, is exactly what happens when you install a developer release straight from version control repos 💀.

Defaults to false.

  • --interactive — flips the configuration (Makefile.PL and Build.PL) into interactive mode, so you actually get to answer the questions for dists that need custom config, or for Task:: distributions. Defaults to false, and you can hit it with --no-interactive to override it when it's been set in the default options inside PERL_CPANM_OPT 🫶
  • --pp, --pureperl — prefers a pure perl build of modules, by setting PUREPERL_ONLY=1 for MakeMaker and --pureperl-only for Build.PL based distributions. Heads up though: not every CPAN module supports this convention yet 🙈
  • --with-recommends, --with-suggests — EXPERIMENTAL: installs dependencies declared as recommends and suggests respectively, per the META spec. When those dependencies fail to install, cpanms just keeps going, because like... they're only a recommendation/suggestion, bestie, it's not that deep 🎀

Turning this on could legit create a circular dependency for a few modules on CPAN — that's when recommends pulls in a module that recommends the original right back. Messy.

There's also --without-recommend and --without-suggests to override the default decision made earlier in PERL_CPANM_OPT.

Defaults to false for both.

  • --with-develop — EXPERIMENTAL: installs develop phase dependencies in META files or cpanfile when used with --installdeps. Defaults to false.
  • --with-configure — EXPERIMENTAL: installs configure phase dependencies in cpanfile when used 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.
cpanms --with-feature=opt_csv Spreadsheet::Read

You can also pick the features interactively when the --interactive option is on ✨

--with-all-features enables every optional feature, and --without-feature lets you select one to disable.

  • --configure-timeout, --build-timeout, --test-timeout — sets the timeout length (in seconds) to wait on the configure, build and test process. Current default values are: 60 for configure, 3600 for build and 1800 for test ⏳
  • --configure-args, --build-args, --test-args, --install-args — EXPERIMENTAL: passes arguments for the configure/build/test/install commands respectively, for a given module you're installing.
cpanms DBD::mysql --configure-args="--cflags=... --libs=..."

The argument is only enabled for the module you passed as a command line argument — not for dependencies. iykyk 💅

  • --scandeps — DEPRECATED: scans the depencencies of the 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's genuinely useful to just type:

cpanms --scandeps Catalyst::Runtime

and then you can be sure about which modules will be installed. Chef's kiss for pre-flight checks.

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

  • --format — DEPRECATED: determines what format to display the scanned dependency tree in. 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. The 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.

  • dists — dists is a special output format, where it prints the distribution filename in 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 any extra dependencies. Combine it with the -L option and it's lowkey iconic for replaying installations on other machines 🔥

  • --save-dists — specifies the optional directory path to copy downloaded tarballs into, 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 — say it came from a local file or from GitHub — then it gets saved under vendor/Foo-Bar-version.tar.gz 📦

  • --uninst-shadows — uninstalls the shadow files of the distribution you're installing. This clears up the confusion when 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 cpanms as root and use INSTALL_BASE or equivalent to specify a custom installation path, you SHOULD disable this option so you won't accidentally uninstall dual-life modules from the core include path. Like, genuinely, do not skip this one 😭

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 — because with 5.12 @INC contains the site_perl directory before the perl core library path, so uninstalling shadows isn't necessary anymore and does more harm by deleting files from the core library path 💀
  • --uninstall, -U — uninstalls a module from the library path. It finds a packlist for the given modules, and removes all the files included in the same distribution.

If you enable local::lib, it only removes files from the local::lib directory 🫶

If you try to uninstall a module in the perl directory (i.e. a core module), an error will be thrown.

A dialog will be prompted to confirm the files to be deleted. If you pass -f as well, the dialog gets skipped and the uninstallation is forced ⚠️

  • --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.
  • --skip-installed — specifies whether a module given on the command line is skipped if its latest version is already installed. Defaults to true.
NOTE: the PERL5LIB environment variable has to be correctly set for this to work with modules installed using local::lib — unless you always use the -l option. Just a lil heads up 💖
  • --skip-satisfied — EXPERIMENTAL: specifies whether a module (and version) given on the command line is skipped if it's already installed.

So if you run:

cpanms --skip-satisfied CGI DBI~1.2

cpanms won't install them if you already have CGI (whatever version) or have DBI at a version higher than 1.2. It's 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 no version at all, which means any version) is installed 💅

Defaults to false.

  • --verify — verifies the integrity of distribution files retrieved from CPAN using the CHECKSUMS file, and the SIGNATURES file (if found in the distribution). Defaults to false.
Using this option does not verify the integrity of the CHECKSUMS file itself, and it's unsafe to rely on this option if you're using a CPAN mirror that you do not trust. Like, fr fr, be careful 🔒
  • --report-perl-version — whether it reports the locally installed perl version to the various web servers as part of User-Agent. Defaults to true unless CI related environment variables such as TRAVIS, CI or AUTOMATED_TESTING are enabled. You can disable it with --no-report-perl-version 🕵️‍♀️
  • --auto-cleanup — specifies the number of days in which cpanm's work directories expire. Defaults to 7, which means old work directories get cleaned up in one week 🧹

You can set the value to 0 to make cpan never cleanup those directories.

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

Defaults to true (man pages generated) unless the -L|--local-lib-contained option is supplied, in which case it's set to false. You can disable it with --no-man-pages 📖

  • --lwp — uses the LWP module to download stuff over HTTP. Defaults to true, and you can say --no-lwp to disable using LWP, which is what you want when you're upgrading LWP from CPAN on some broken perl systems 🔧
  • --wget — uses GNU Wget (if available) to download stuff. Defaults to true, and you can say --no-wget to disable using Wget.
  • --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 all set to true (which is the default), cpanms tries LWP, Wget, cURL and HTTP::Tiny (in that order) and uses the first one available ✨

🌈 ENVIRONMENT VARIABLES 🌈

  • PERL_CPANM_HOME — the directory cpanms should use to store downloads and build and test modules. Defaults to the .cpanm directory in your user's home directory 🏠
  • PERL_CPANM_OPT — if set, adds a set of default options to every cpanms command. These options come first, and so are overridden by command-line options. So it's the ultimate "set it and forget it" bestie 💅

👀 SEE ALSO 👀

App::cpanminus

🐛 BUGS 🐛

This version of cpanminus, distributed under the name of cpanms, has been modified by Rubicon for Alpine Linux. If you find any bugs that are specific to this version (not reproducible with the original cpanminus distributed in Alpine under the name of cpanm), please do not bother the original author 🙏 — instead file a bug report at: https://gitlab.alpinelinux.org/alpine/aports/-/issues

Copyright 2010- Tatsuhiko Miyagawa.

🫶 AUTHOR 🫶

Tatsuhiko Miyagawa

okay that's the whole page, you're free bestie! this one's perl v5.42.2, dated 2024-10-30, and it's CPANMS(1) — slay, go install something 💖✨🎀

📦 where this page comes from