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.
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".
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
|-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.|
Upgrades itself. Its just an alias for:
|--info||Displays the distribution information in AUTHOR/Dist-Name-ver.tar.gz format in the standard out.|
Installs the dependencies of the target distribution but wont build
itself. Handy if you want to try the application from a version
controlled repository such as git.
|--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.|
You can specify the default options in PERL_CPANM_OPT environment variable.
-f, --force Force install modules even when testing failed. -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 youve 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. -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 dont 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 theyre already installed.
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 <B>NOTB> reliably work with perl installations supplied by operating system vendors that strips standard modules from perl, such as RHEL, Fedora and CentOS, <B>UNLESSB> 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 Dont 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.
cpanm --mirror file:///path/to/mirror cpanm --mirror ~/minicpan # Because shell expands ~ to /home/user
Defaults to http://www.cpan.org/.
--mirror-only Download the mirrors 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. --from, -M
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.
--mirror-index <B>EXPERIMENTALB>: Specifies the file path to 02packages.details.txt for module search index. --cpanmetadb <B>EXPERIMENTALB>: Specifies an alternate URI for CPAN MetaDB index lookups. --metacpan Prefers MetaCPAN API over CPAN MetaDB. --cpanfile <B>EXPERIMENTALB>: Specified 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 whats 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 its set in the default options in PERL_CPANM_OPT.
--dev <B>EXPERIMENTALB>: search for a newer developer release as well. Defaults to false. --reinstall 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 the check, so:
cpanm --reinstall Plack
Defaults to false.
--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 its 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. --with-recommends, --with-suggests <B>EXPERIMENTALB>: Installs dependencies declared as recommends and suggests respectively, per META spec. When these dependencies fail to install, cpanm continues the installation, since theyre 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.
Theres also --without-recommend and --without-suggests to override the default decision made earlier in PERL_CPANM_OPT.
Defaults to false for both.
--with-develop <B>EXPERIMENTALB>: Installs develop phase dependencies in META files or cpanfile when used with --installdeps. Defaults to false. --with-feature, --without-feature, --with-all-features <B>EXPERIMENTALB>: Specifies the feature to enable, if a module supports optional features per META spec 2.0.
the features can also be interactively chosen when --interactive option is enabled.
--configure-timeout, --build-timeout, --test-timeout Specify the timeout length (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. --configure-args, --build-args, --test-args, --install-args <B>EXPERIMENTALB>: Pass 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.
--scandeps <B>DEPRECATEDB>: Scans the depencencies of given modules and output the tree in a text format. (See --format below for more options)
Because this command doesnt actually install any distributions, it will be useful that by typing:
cpanm --scandeps Catalyst::Runtime
you can make sure what modules will be installed.
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 <B>DEPRECATEDB>: 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.
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.
--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 --uninst-shadows Uninstalls the shadow files of the distribution that youre installing. This eliminates the confusion if youre 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 wont accidentally uninstall dual-life modules from the core include path.
<B>NOTEB>: 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.
--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.
If you try to uninstall a module in perl directory (i.e. core module), an error will be thrown.
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.
--cascade-search <B>EXPERIMENTALB>: Specifies whether to cascade search when you specify multiple mirrors and a mirror doesnt have a module or has a lower version of the module than requested. Defaults to false. --skip-installed Specifies whether a module given in the command line is skipped if its latest version is already installed. Defaults to true. --skip-satisfied <B>EXPERIMENTALB>: Specifies whether a module (and version) given in the command line is skipped if its already installed.
If you run:
cpanm wont 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.
Defaults to false.
--verify Verify the integrity of distribution files retrieved from PAUSE using CHECKSUMS and SIGNATURES (if found). Defaults to false. --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. --auto-cleanup Specifies the number of days in which cpanms 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.
--man-pages Generates man pages for executables (man1) and libraries (man3). --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. --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 dont support the --retry-connrefused option used by cpanm). --curl Uses cURL (if available) to download stuff. Defaults to true, and you can say --no-curl to disable using cURL.
Copyright 2010- Tatsuhiko Miyagawa.
|perl v5.20.3||CPANM (1)||2015-06-29|