1CPANM(1) User Contributed Perl Documentation CPANM(1)
2
6 cpanm - get, unpack build and install modules from CPAN
7
9 cpanm Test::More # install Test::More
10 cpanm MIYAGAWA/Plack-0.99_05.tar.gz # full distribution path
11 cpanm http://example.org/LDS/CGI.pm-3.20.tar.gz # install from URL
12 cpanm ~/dists/MyCompany-Enterprise-1.00.tar.gz # install from a local file
13 cpanm --interactive Task::Kensho # Configure interactively
14 cpanm . # install from local directory
15 cpanm --installdeps . # install all the deps for the current directory
16 cpanm -L extlib Plack # install Plack and all non-core deps into extlib
17 cpanm --mirror http://cpan.cpantesters.org/ DBI # use the fast-syncing mirror
18 cpanm --from https://cpan.metacpan.org/ Plack # use only the HTTPS mirror
19
21 (arguments)
22 Command line arguments can be either a module name, distribution
23 file, local file path, HTTP URL or git repository URL. Following
24 commands will all work as you expect.
25 cpanm Plack
27 cpanm Plack/Request.pm
28 cpanm MIYAGAWA/Plack-1.0000.tar.gz
29 cpanm /path/to/Plack-1.0000.tar.gz
30 cpanm http://cpan.metacpan.org/authors/id/M/MI/MIYAGAWA/Plack-0.9990.tar.gz
31 cpanm git://github.com/plack/Plack.git
32 Additionally, you can use the notation using "~" and "@" to specify
34 version for a given module. "~" specifies the version requirement
35 in the CPAN::Meta::Spec format, while "@" pins the exact version,
36 and is a shortcut for "~"== VERSION"".
37 cpanm Plack~1.0000 # 1.0000 or later
39 cpanm Plack~">= 1.0000, < 2.0000" # latest of 1.xxxx
40 cpanm Plack@0.9990 # specific version. same as Plack~"== 0.9990"
41 The version query including specific version or range will be sent
43 to MetaCPAN to search for previous releases. The query will search
44 for BackPAN archives by default, unless you specify "--dev" option,
45 in which case, archived versions will be filtered out.
46 For a git repository, you can specify a branch, tag, or commit SHA
48 to build. The default is "master"
49 cpanm git://github.com/plack/Plack.git@1.0000 # tag
51 cpanm git://github.com/plack/Plack.git@devel # branch
52 -i, --install
54 Installs the modules. This is a default behavior and this is just a
55 compatibility option to make it work like cpan or cpanp.
56 --self-upgrade
58 Upgrades itself. It's just an alias for:
59 cpanm App::cpanminus
61 --info
63 Displays the distribution information in
64 "AUTHOR/Dist-Name-ver.tar.gz" format in the standard out.
65 --installdeps
67 Installs the dependencies of the target distribution but won't
68 build itself. Handy if you want to try the application from a
69 version controlled repository such as git.
70 cpanm --installdeps .
72 --look
74 Download and unpack the distribution and then open the directory
75 with your shell. Handy to poke around the source code or do manual
76 testing.
77 -h, --help
79 Displays the help message.
80 -V, --version
82 Displays the version number.
83
85 You can specify the default options in "PERL_CPANM_OPT" environment
86 variable.
87 -f, --force
89 Force install modules even when testing failed.
90 -n, --notest
92 Skip the testing of modules. Use this only when you just want to
93 save time for installing hundreds of distributions to the same perl
94 and architecture you've already tested to make sure it builds fine.
95 Defaults to false, and you can say "--no-notest" to override when
97 it is set in the default options in "PERL_CPANM_OPT".
98 --test-only
100 Run the tests only, and do not install the specified module or
101 distributions. Handy if you want to verify the new (or even old)
102 releases pass its unit tests without installing the module.
103 Note that if you specify this option with a module or distribution
105 that has dependencies, these dependencies will be installed if you
106 don't currently have them.
107 -S, --sudo
109 Switch to the root user with "sudo" when installing modules. Use
110 this if you want to install modules to the system perl include
111 path.
112 Defaults to false, and you can say "--no-sudo" to override when it
114 is set in the default options in "PERL_CPANM_OPT".
115 -v, --verbose
117 Makes the output verbose. It also enables the interactive
118 configuration. (See --interactive)
119 -q, --quiet
121 Makes the output even more quiet than the default. It only shows
122 the successful/failed dependencies to the output.
123 -l, --local-lib
125 Sets the local::lib compatible path to install modules to. You
126 don't need to set this if you already configure the shell
127 environment variables using local::lib, but this can be used to
128 override that as well.
129 -L, --local-lib-contained
131 Same with "--local-lib" but with --self-contained set. All non-
132 core dependencies will be installed even if they're already
133 installed.
134 For instance,
136 cpanm -L extlib Plack
138 would install Plack and all of its non-core dependencies into the
140 directory "extlib", which can be loaded from your application with:
141 use local::lib '/path/to/extlib';
143 Note that this option does NOT reliably work with perl
145 installations supplied by operating system vendors that strips
146 standard modules from perl, such as RHEL, Fedora and CentOS, UNLESS
147 you also install packages supplying all the modules that have been
148 stripped. For these systems you will probably want to install the
149 "perl-core" meta-package which does just that.
150 --self-contained
152 When examining the dependencies, assume no non-core modules are
153 installed on the system. Handy if you want to bundle application
154 dependencies in one directory so you can distribute to other
155 machines.
156 --exclude-vendor
158 Don't include modules installed under the 'vendor' paths when
159 searching for core modules when the "--self-contained" flag is in
160 effect. This restores the behaviour from before version 1.7023
161 --mirror
163 Specifies the base URL for the CPAN mirror to use, such as
164 "http://cpan.cpantesters.org/" (you can omit the trailing slash).
165 You can specify multiple mirror URLs by repeating the command line
166 option.
167 You can use a local directory that has a CPAN mirror structure
169 (created by tools such as OrePAN or Pinto) by using a special URL
170 scheme "file://". If the given URL begins with `/` (without any
171 scheme), it is considered as a file scheme as well.
172 cpanm --mirror file:///path/to/mirror
174 cpanm --mirror ~/minicpan # Because shell expands ~ to /home/user
175 Defaults to "http://www.cpan.org/".
177 --mirror-only
179 Download the mirror's 02packages.details.txt.gz index file instead
180 of querying the CPAN Meta DB. This will also effectively opt out
181 sending your local perl versions to backend database servers such
182 as CPAN Meta DB and MetaCPAN.
183 Select this option if you are using a local mirror of CPAN, such as
185 minicpan when you're offline, or your own CPAN index (a.k.a
186 darkpan).
187 --from, -M
189 cpanm -M https://cpan.metacpan.org/
190 cpanm --from https://cpan.metacpan.org/
191 Use the given mirror URL and its index as the only source to search
193 and download modules from.
194 It works similar to "--mirror" and "--mirror-only" combined, with a
196 small difference: unlike "--mirror" which appends the URL to the
197 list of mirrors, "--from" (or "-M" for short) uses the specified
198 URL as its only source to download index and modules from. This
199 makes the option always override the default mirror, which might
200 have been set via global options such as the one set by
201 "PERL_CPANM_OPT" environment variable.
202 Tip: It might be useful if you name these options with your shell
204 aliases, like:
205 alias minicpanm='cpanm --from ~/minicpan'
207 alias darkpan='cpanm --from http://mycompany.example.com/DPAN'
208 --mirror-index
210 EXPERIMENTAL: Specifies the file path to "02packages.details.txt"
211 for module search index.
212 --cpanmetadb
214 EXPERIMENTAL: Specifies an alternate URI for CPAN MetaDB index
215 lookups.
216 --metacpan
218 Prefers MetaCPAN API over CPAN MetaDB.
219 --cpanfile
221 EXPERIMENTAL: Specified an alternate path for cpanfile to search
222 for, when "--installdeps" command is in use. Defaults to
223 "cpanfile".
224 --prompt
226 Prompts when a test fails so that you can skip, force install,
227 retry or look in the shell to see what's going wrong. It also
228 prompts when one of the dependency failed if you want to proceed
229 the installation.
230 Defaults to false, and you can say "--no-prompt" to override if
232 it's set in the default options in "PERL_CPANM_OPT".
233 --dev
235 EXPERIMENTAL: search for a newer developer release as well.
236 Defaults to false.
237 --reinstall
239 cpanm, when given a module name in the command line (i.e. "cpanm
240 Plack"), checks the locally installed version first and skips if it
241 is already installed. This option makes it skip the check, so:
242 cpanm --reinstall Plack
244 would reinstall Plack even if your locally installed version is
246 latest, or even newer (which would happen if you install a
247 developer release from version control repositories).
248 Defaults to false.
250 --interactive
252 Makes the configuration (such as "Makefile.PL" and "Build.PL")
253 interactive, so you can answer questions in the distribution that
254 requires custom configuration or Task:: distributions.
255 Defaults to false, and you can say "--no-interactive" to override
257 when it's set in the default options in "PERL_CPANM_OPT".
258 --pp, --pureperl
260 Prefer Pure perl build of modules by setting "PUREPERL_ONLY=1" for
261 MakeMaker and "--pureperl-only" for Build.PL based distributions.
262 Note that not all of the CPAN modules support this convention yet.
263 --with-recommends, --with-suggests
265 EXPERIMENTAL: Installs dependencies declared as "recommends" and
266 "suggests" respectively, per META spec. When these dependencies
267 fail to install, cpanm continues the installation, since they're
268 just recommendation/suggestion.
269 Enabling this could potentially make a circular dependency for a
271 few modules on CPAN, when "recommends" adds a module that
272 "recommends" back the module in return.
273 There's also "--without-recommend" and "--without-suggests" to
275 override the default decision made earlier in "PERL_CPANM_OPT".
276 Defaults to false for both.
278 --with-develop
280 EXPERIMENTAL: Installs develop phase dependencies in META files or
281 "cpanfile" when used with "--installdeps". Defaults to false.
282 --with-configure
284 EXPERIMENTAL: Installs configure phase dependencies in "cpanfile"
285 when used with "--installdeps". Defaults to false.
286 --with-feature, --without-feature, --with-all-features
288 EXPERIMENTAL: Specifies the feature to enable, if a module supports
289 optional features per META spec 2.0.
290 cpanm --with-feature=opt_csv Spreadsheet::Read
292 the features can also be interactively chosen when "--interactive"
294 option is enabled.
295 "--with-all-features" enables all the optional features, and
297 "--without-feature" can select a feature to disable.
298 --configure-timeout, --build-timeout, --test-timeout
300 Specify the timeout length (in seconds) to wait for the configure,
301 build and test process. Current default values are: 60 for
302 configure, 3600 for build and 1800 for test.
303 --configure-args, --build-args, --test-args, --install-args
305 EXPERIMENTAL: Pass arguments for configure/build/test/install
306 commands respectively, for a given module to install.
307 cpanm DBD::mysql --configure-args="--cflags=... --libs=..."
309 The argument is only enabled for the module passed as a command
311 line argument, not dependencies.
312 --scandeps
314 DEPRECATED: Scans the depencencies of given modules and output the
315 tree in a text format. (See "--format" below for more options)
316 Because this command doesn't actually install any distributions, it
318 will be useful that by typing:
319 cpanm --scandeps Catalyst::Runtime
321 you can make sure what modules will be installed.
323 This command takes into account which modules you already have
325 installed in your system. If you want to see what modules will be
326 installed against a vanilla perl installation, you might want to
327 combine it with "-L" option.
328 --format
330 DEPRECATED: Determines what format to display the scanned
331 dependency tree. Available options are "tree", "json", "yaml" and
332 "dists".
333 tree Displays the tree in a plain text format. This is the
335 default value.
336 json, yaml
338 Outputs the tree in a JSON or YAML format. JSON and YAML
339 modules need to be installed respectively. The output tree
340 is represented as a recursive tuple of:
341 [ distribution, dependencies ]
343 and the container is an array containing the root elements.
345 Note that there may be multiple root nodes, since you can
346 give multiple modules to the "--scandeps" command.
347 dists "dists" is a special output format, where it prints the
349 distribution filename in the depth first order after the
350 dependency resolution, like:
351 GAAS/MIME-Base64-3.13.tar.gz
353 GAAS/URI-1.58.tar.gz
354 PETDANCE/HTML-Tagset-3.20.tar.gz
355 GAAS/HTML-Parser-3.68.tar.gz
356 GAAS/libwww-perl-5.837.tar.gz
357 which means you can install these distributions in this
359 order without extra dependencies. When combined with "-L"
360 option, it will be useful to replay installations on other
361 machines.
362 --save-dists
364 Specifies the optional directory path to copy downloaded tarballs
365 in the CPAN mirror compatible directory structure i.e.
366 authors/id/A/AU/AUTHORS/Foo-Bar-version.tar.gz
367 If the distro tarball did not come from CPAN, for example from a
369 local file or from GitHub, then it will be saved under
370 vendor/Foo-Bar-version.tar.gz.
371 --uninst-shadows
373 Uninstalls the shadow files of the distribution that you're
374 installing. This eliminates the confusion if you're trying to
375 install core (dual-life) modules from CPAN against perl 5.10 or
376 older, or modules that used to be XS-based but switched to pure
377 perl at some version.
378 If you run cpanm as root and use "INSTALL_BASE" or equivalent to
380 specify custom installation path, you SHOULD disable this option so
381 you won't accidentally uninstall dual-life modules from the core
382 include path.
383 Defaults to true if your perl version is smaller than 5.12, and you
385 can disable that with "--no-uninst-shadows".
386 NOTE: Since version 1.3000 this flag is turned off by default for
388 perl newer than 5.12, since with 5.12 @INC contains site_perl
389 directory before the perl core library path, and uninstalling
390 shadows is not necessary anymore and does more harm by deleting
391 files from the core library path.
392 --uninstall, -U
394 Uninstalls a module from the library path. It finds a packlist for
395 given modules, and removes all the files included in the same
396 distribution.
397 If you enable local::lib, it only removes files from the local::lib
399 directory.
400 If you try to uninstall a module in "perl" directory (i.e. core
402 module), an error will be thrown.
403 A dialog will be prompted to confirm the files to be deleted. If
405 you pass "-f" option as well, the dialog will be skipped and
406 uninstallation will be forced.
407 --cascade-search
409 EXPERIMENTAL: Specifies whether to cascade search when you specify
410 multiple mirrors and a mirror doesn't have a module or has a lower
411 version of the module than requested. Defaults to false.
412 --skip-installed
414 Specifies whether a module given in the command line is skipped if
415 its latest version is already installed. Defaults to true.
416 NOTE: The "PERL5LIB" environment variable have to be correctly set
418 for this to work with modules installed using local::lib, unless
419 you always use the "-l" option.
420 --skip-satisfied
422 EXPERIMENTAL: Specifies whether a module (and version) given in the
423 command line is skipped if it's already installed.
424 If you run:
426 cpanm --skip-satisfied CGI DBI~1.2
428 cpanm won't install them if you already have CGI (for whatever
430 versions) or have DBI with version higher than 1.2. It is similar
431 to "--skip-installed" but while "--skip-installed" checks if the
432 latest version of CPAN is installed, "--skip-satisfied" checks if a
433 requested version (or not, which means any version) is installed.
434 Defaults to false.
436 --verify
438 Verify the integrity of distribution files retrieved from CPAN
439 using CHECKSUMS file, and SIGNATURES file (if found in the
440 distribution). Defaults to false.
441 Using this option does not verify the integrity of the CHECKSUMS
443 file, and it's unsafe to rely on this option if you're using a CPAN
444 mirror that you do not trust.
445 --report-perl-version
447 Whether it reports the locally installed perl version to the
448 various web server as part of User-Agent. Defaults to true unless
449 CI related environment variables such as "TRAVIS", "CI" or
450 "AUTOMATED_TESTING" is enabled. You can disable it by using
451 "--no-report-perl-version".
452 --auto-cleanup
454 Specifies the number of days in which cpanm's work directories
455 expire. Defaults to 7, which means old work directories will be
456 cleaned up in one week.
457 You can set the value to 0 to make cpan never cleanup those
459 directories.
460 --man-pages
462 Generates man pages for executables (man1) and libraries (man3).
463 Defaults to true (man pages generated) unless
465 "-L|--local-lib-contained" option is supplied in which case it's
466 set to false. You can disable it with "--no-man-pages".
467 --lwp
469 Uses LWP module to download stuff over HTTP. Defaults to true, and
470 you can say "--no-lwp" to disable using LWP, when you want to
471 upgrade LWP from CPAN on some broken perl systems.
472 --wget
474 Uses GNU Wget (if available) to download stuff. Defaults to true,
475 and you can say "--no-wget" to disable using Wget (versions of Wget
476 older than 1.9 don't support the "--retry-connrefused" option used
477 by cpanm).
478 --curl
480 Uses cURL (if available) to download stuff. Defaults to true, and
481 you can say "--no-curl" to disable using cURL.
482 Normally with "--lwp", "--wget" and "--curl" options set to true
484 (which is the default) cpanm tries LWP, Wget, cURL and HTTP::Tiny
485 (in that order) and uses the first one available.
486
488 PERL_CPANM_HOME
489 The directory cpanm should use to store downloads and build and
490 test modules. Defaults to the ".cpanm" directory in your user's
491 home directory.
492 PERL_CPANM_OPT
494 If set, adds a set of default options to every cpanm command. These
495 options come first, and so are overridden by command-line options.
496
498 App::cpanminus
499
501 Copyright 2010- Tatsuhiko Miyagawa.
502
504 Tatsuhiko Miyagawa
505perl v5.38.0 2023-08-01 CPANM(1)