1CPANM(1)              User Contributed Perl Documentation             CPANM(1)
2
3
4

NAME

6       cpanm - get, unpack build and install modules from CPAN
7

SYNOPSIS

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

COMMANDS

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
26               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
33           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
38               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
42           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
47           For a git repository, you can specify a branch, tag, or commit SHA
48           to build. The default is "master"
49
50               cpanm git://github.com/plack/Plack.git@1.0000        # tag
51               cpanm git://github.com/plack/Plack.git@devel         # branch
52
53       -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
57       --self-upgrade
58           Upgrades itself. It's just an alias for:
59
60             cpanm App::cpanminus
61
62       --info
63           Displays the distribution information in
64           "AUTHOR/Dist-Name-ver.tar.gz" format in the standard out.
65
66       --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
71             cpanm --installdeps .
72
73       --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
78       -h, --help
79           Displays the help message.
80
81       -V, --version
82           Displays the version number.
83

OPTIONS

85       You can specify the default options in "PERL_CPANM_OPT" environment
86       variable.
87
88       -f, --force
89           Force install modules even when testing failed.
90
91       -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
96           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
99       --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
104           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
108       -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
113           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
116       -v, --verbose
117           Makes the output verbose. It also enables the interactive
118           configuration. (See --interactive)
119
120       -q, --quiet
121           Makes the output even more quiet than the default. It only shows
122           the successful/failed dependencies to the output.
123
124       -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
130       -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
135           For instance,
136
137             cpanm -L extlib Plack
138
139           would install Plack and all of its non-core dependencies into the
140           directory "extlib", which can be loaded from your application with:
141
142             use local::lib '/path/to/extlib';
143
144           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
151       --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
157       --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
162       --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
168           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
173             cpanm --mirror file:///path/to/mirror
174             cpanm --mirror ~/minicpan      # Because shell expands ~ to /home/user
175
176           Defaults to "http://www.cpan.org/".
177
178       --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
184           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
188       --from, -M
189             cpanm -M https://cpan.metacpan.org/
190             cpanm --from https://cpan.metacpan.org/
191
192           Use the given mirror URL and its index as the only source to search
193           and download modules from.
194
195           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
203           Tip: It might be useful if you name these options with your shell
204           aliases, like:
205
206             alias minicpanm='cpanm --from ~/minicpan'
207             alias darkpan='cpanm --from http://mycompany.example.com/DPAN'
208
209       --mirror-index
210           EXPERIMENTAL: Specifies the file path to "02packages.details.txt"
211           for module search index.
212
213       --cpanmetadb
214           EXPERIMENTAL: Specifies an alternate URI for CPAN MetaDB index
215           lookups.
216
217       --metacpan
218           Prefers MetaCPAN API over CPAN MetaDB.
219
220       --cpanfile
221           EXPERIMENTAL: Specified an alternate path for cpanfile to search
222           for, when "--installdeps" command is in use. Defaults to
223           "cpanfile".
224
225       --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
231           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
234       --dev
235           EXPERIMENTAL: search for a newer developer release as well.
236           Defaults to false.
237
238       --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
243             cpanm --reinstall Plack
244
245           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
249           Defaults to false.
250
251       --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
256           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
259       --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
264       --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
270           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
274           There's also "--without-recommend" and "--without-suggests" to
275           override the default decision made earlier in "PERL_CPANM_OPT".
276
277           Defaults to false for both.
278
279       --with-develop
280           EXPERIMENTAL: Installs develop phase dependencies in META files or
281           "cpanfile" when used with "--installdeps". Defaults to false.
282
283       --with-configure
284           EXPERIMENTAL: Installs configure phase dependencies in "cpanfile"
285           when used with "--installdeps". Defaults to false.
286
287       --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
291               cpanm --with-feature=opt_csv Spreadsheet::Read
292
293           the features can also be interactively chosen when "--interactive"
294           option is enabled.
295
296           "--with-all-features" enables all the optional features, and
297           "--without-feature" can select a feature to disable.
298
299       --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
304       --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
308               cpanm DBD::mysql --configure-args="--cflags=... --libs=..."
309
310           The argument is only enabled for the module passed as a command
311           line argument, not dependencies.
312
313       --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
317           Because this command doesn't actually install any distributions, it
318           will be useful that by typing:
319
320             cpanm --scandeps Catalyst::Runtime
321
322           you can make sure what modules will be installed.
323
324           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
329       --format
330           DEPRECATED: Determines what format to display the scanned
331           dependency tree. Available options are "tree", "json", "yaml" and
332           "dists".
333
334           tree    Displays the tree in a plain text format. This is the
335                   default value.
336
337           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
342                     [ distribution, dependencies ]
343
344                   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
348           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
352                     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
358                   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
363       --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
368           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
372       --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
379           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
384           Defaults to true if your perl version is smaller than 5.12, and you
385           can disable that with "--no-uninst-shadows".
386
387           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
393       --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
398           If you enable local::lib, it only removes files from the local::lib
399           directory.
400
401           If you try to uninstall a module in "perl" directory (i.e. core
402           module), an error will be thrown.
403
404           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
408       --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
413       --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
417           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
421       --skip-satisfied
422           EXPERIMENTAL: Specifies whether a module (and version) given in the
423           command line is skipped if it's already installed.
424
425           If you run:
426
427             cpanm --skip-satisfied CGI DBI~1.2
428
429           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
435           Defaults to false.
436
437       --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
442           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
446       --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
453       --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
458           You can set the value to 0 to make cpan never cleanup those
459           directories.
460
461       --man-pages
462           Generates man pages for executables (man1) and libraries (man3).
463
464           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
468       --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
473       --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
479       --curl
480           Uses cURL (if available) to download stuff. Defaults to true, and
481           you can say "--no-curl" to disable using cURL.
482
483           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

ENVIRONMENT VARIABLES

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
493       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

SEE ALSO

498       App::cpanminus
499
501       Copyright 2010- Tatsuhiko Miyagawa.
502

AUTHOR

504       Tatsuhiko Miyagawa
505
506
507
508perl v5.38.0                      2023-08-01                          CPANM(1)
Impressum