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

COMMANDS

20       (arguments)
21           Command line arguments can be either a module name, distribution
22           file, local file path, HTTP URL or git repository URL. Following
23           commands will all work as you expect.
24
25               cpanm Plack
26               cpanm Plack/Request.pm
27               cpanm MIYAGAWA/Plack-1.0000.tar.gz
28               cpanm /path/to/Plack-1.0000.tar.gz
29               cpanm http://cpan.metacpan.org/authors/id/M/MI/MIYAGAWA/Plack-0.9990.tar.gz
30               cpanm git://github.com/miyagawa/Plack.git
31
32           Additionally, you can use the notation using "~" and "@" to specify
33           version for a given module. "~" specifies the version requirement
34           in the CPAN::Meta::Spec format, while "@" pins the exact version,
35           and is a shortcut for "~"== VERSION"".
36
37               cpanm Plack~1.0000                 # 1.0000 or later
38               cpanm Plack~">= 1.0000, < 2.0000"  # latest of 1.xxxx
39               cpanm Plack@0.9990                 # specific version. same as Plack~"== 0.9990"
40
41           The version query including specific version or range will be sent
42           to MetaCPAN to search for previous releases. The query will search
43           for BackPAN archives by default, unless you specify "--dev" option,
44           in which case, archived versions will be filtered out.
45
46           For a git repository, you can specify a branch, tag, or commit SHA
47           to build. The default is "master"
48
49               cpanm git://github.com/miyagawa/Plack.git@1.0000        # tag
50               cpanm git://github.com/miyagawa/Plack.git@devel         # branch
51
52       -i, --install
53           Installs the modules. This is a default behavior and this is just a
54           compatibility option to make it work like cpan or cpanp.
55
56       --self-upgrade
57           Upgrades itself. It's just an alias for:
58
59             cpanm App::cpanminus
60
61       --info
62           Displays the distribution information in
63           "AUTHOR/Dist-Name-ver.tar.gz" format in the standard out.
64
65       --installdeps
66           Installs the dependencies of the target distribution but won't
67           build itself. Handy if you want to try the application from a
68           version controlled repository such as git.
69
70             cpanm --installdeps .
71
72       --look
73           Download and unpack the distribution and then open the directory
74           with your shell. Handy to poke around the source code or do manual
75           testing.
76
77       -U, --uninstall
78           EXPERIMENTAL: Uninstalls the modules. Will remove the distribution
79           files from your library path using the ".packlist" file.
80
81           When used with "-l" or "-L", only the files under the local::lib
82           directory will be removed.
83
84           NOTE: If you have the "dual-life" module in multiple locations
85           (i.e. "site_perl" and "perl" library path, with perl 5.12 or
86           later), only the files in "site_perl" will be deleted.
87
88           If the distribution has bin scripts and man, they will be kept in
89           case the core installation still references that, although there's
90           no guarantee that the script will continue working as expected with
91           the older version of .pm files.
92
93       -h, --help
94           Displays the help message.
95
96       -V, --version
97           Displays the version number.
98

OPTIONS

100       You can specify the default options in "PERL_CPANM_OPT" environment
101       variable.
102
103       -f, --force
104           Force install modules even when testing failed.
105
106       -n, --notest
107           Skip the testing of modules. Use this only when you just want to
108           save time for installing hundreds of distributions to the same perl
109           and architecture you've already tested to make sure it builds fine.
110
111           Defaults to false, and you can say "--no-notest" to override when
112           it is set in the default options in "PERL_CPANM_OPT".
113
114       --test-only
115           Run the tests only, and do not install the specified module or
116           distributions. Handy if you want to verify the new (or even old)
117           releases pass its unit tests without installing the module.
118
119           Note that if you specify this option with a module or distribution
120           that has dependencies, these dependencies will be installed if you
121           don't currently have them.
122
123       -S, --sudo
124           Switch to the root user with "sudo" when installing modules. Use
125           this if you want to install modules to the system perl include
126           path.
127
128           Defaults to false, and you can say "--no-sudo" to override when it
129           is set in the default options in "PERL_CPANM_OPT".
130
131       -v, --verbose
132           Makes the output verbose. It also enables the interactive
133           configuration. (See --interactive)
134
135       -q, --quiet
136           Makes the output even more quiet than the default. It only shows
137           the successful/failed dependencies to the output.
138
139       -l, --local-lib
140           Sets the local::lib compatible path to install modules to. You
141           don't need to set this if you already configure the shell
142           environment variables using local::lib, but this can be used to
143           override that as well.
144
145       -L, --local-lib-contained
146           Same with "--local-lib" but with --self-contained set.  All non-
147           core dependencies will be installed even if they're already
148           installed.
149
150           For instance,
151
152             cpanm -L extlib Plack
153
154           would install Plack and all of its non-core dependencies into the
155           directory "extlib", which can be loaded from your application with:
156
157             use local::lib '/path/to/extlib';
158
159       --self-contained
160           When examining the dependencies, assume no non-core modules are
161           installed on the system. Handy if you want to bundle application
162           dependencies in one directory so you can distribute to other
163           machines.
164
165       --mirror
166           Specifies the base URL for the CPAN mirror to use, such as
167           "http://cpan.cpantesters.org/" (you can omit the trailing slash).
168           You can specify multiple mirror URLs by repeating the command line
169           option.
170
171           You can use a local directory that has a CPAN mirror structure
172           (created by tools such as OrePAN or Pinto) by using a special URL
173           scheme "file://". If the given URL begins with `/` (without any
174           scheme), it is considered as a file scheme as well.
175
176             cpanm --mirror file:///path/to/mirror
177             cpanm --mirror ~/minicpan      # Because shell expands ~ to /home/user
178
179           Defaults to "http://www.cpan.org/".
180
181       --mirror-only
182           Download the mirror's 02packages.details.txt.gz index file instead
183           of querying the CPAN Meta DB. This will also effectively opt out
184           sending your local perl versions to backend database servers such
185           as CPAN Meta DB and MetaCPAN.
186
187           Select this option if you are using a local mirror of CPAN, such as
188           minicpan when you're offline, or your own CPAN index (a.k.a
189           darkpan).
190
191           Tip: It might be useful if you name these mirror options with your
192           shell aliases, like:
193
194             alias minicpanm='cpanm --mirror ~/minicpan --mirror-only'
195             alias darkpan='cpanm --mirror http://mycompany.example.com/DPAN --mirror-only'
196
197       --mirror-index
198           EXPERIMENTAL: Specifies the file path to "02packages.details.txt"
199           for module search index.
200
201       --prompt
202           Prompts when a test fails so that you can skip, force install,
203           retry or look in the shell to see what's going wrong. It also
204           prompts when one of the dependency failed if you want to proceed
205           the installation.
206
207           Defaults to false, and you can say "--no-prompt" to override if
208           it's set in the default options in "PERL_CPANM_OPT".
209
210       --dev
211           EXPERIMENTAL: search for a newer developer release as well.
212           Defaults to false.
213
214       --reinstall
215           cpanm, when given a module name in the command line (i.e. "cpanm
216           Plack"), checks the locally installed version first and skips if it
217           is already installed. This option makes it skip the check, so:
218
219             cpanm --reinstall Plack
220
221           would reinstall Plack even if your locally installed version is
222           latest, or even newer (which would happen if you install a
223           developer release from version control repositories).
224
225           Defaults to false.
226
227       --interactive
228           Makes the configuration (such as "Makefile.PL" and "Build.PL")
229           interactive, so you can answer questions in the distribution that
230           requires custom configuration or Task:: distributions.
231
232           Defaults to false, and you can say "--no-interactive" to override
233           when it's set in the default options in "PERL_CPANM_OPT".
234
235       --pp, --pureperl
236           Prefer Pure perl build of modules by setting "PUREPERL_ONLY=1" for
237           MakeMaker and "--pureperl-only" for Build.PL based distributions.
238           Note that not all of the CPAN modules support this convention yet.
239
240       --with-recommends, --with-suggests
241           EXPERIMENTAL: Installs dependencies declared as "recommends" and
242           "suggests" respectively, per META spec. When these dependencies
243           fail to install, cpanm continues the installation, since they're
244           just recommendation/suggestion.
245
246           Enabling this could potentially make a circular dependency for a
247           few modules on CPAN, when "recommends" adds a module that
248           "recommends" back the module in return.
249
250           There's also "--without-recommend" and "--without-suggests" to
251           override the default decision made earlier in "PERL_CPANM_OPT".
252
253           Defaults to false for both.
254
255       --with-feature, --without-feature, --with-all-features
256           EXPERIMENTAL: Specifies the feature to enable, if a module supports
257           optional features per META spec 2.0.
258
259               cpanm --with-feature=opt_csv Spreadsheet::Read
260
261           the features can also be interactively chosen when "--interactive"
262           option is enabled.
263
264           "--with-all-features" enables all the optional features, and
265           "--without-feature" can select a feature to disable.
266
267       --configure-timeout, --build-timeout, --test-timeout
268           Specify the timeout length (in seconds) to wait for the configure,
269           build and test process. Current default values are: 60 for
270           configure, 3600 for build and 1800 for test.
271
272       --configure-args, --build-args, --test-args, --install-args
273           EXPERIMENTAL: Pass arguments for configure/build/test/install
274           commands respectively, for a given module to install.
275
276               cpanm DBD::mysql --configure-args="--cflags=... --libs=..."
277
278           The argument is only enabled for the module passed as a command
279           line argument, not dependencies.
280
281       --scandeps
282           Scans the depencencies of given modules and output the tree in a
283           text format. (See "--format" below for more options)
284
285           Because this command doesn't actually install any distributions, it
286           will be useful that by typing:
287
288             cpanm --scandeps Catalyst::Runtime
289
290           you can make sure what modules will be installed.
291
292           This command takes into account which modules you already have
293           installed in your system. If you want to see what modules will be
294           installed against a vanilla perl installation, you might want to
295           combine it with "-L" option.
296
297       --format
298           Determines what format to display the scanned dependency tree.
299           Available options are "tree", "json", "yaml" and "dists".
300
301           tree    Displays the tree in a plain text format. This is the
302                   default value.
303
304           json, yaml
305                   Outputs the tree in a JSON or YAML format. JSON and YAML
306                   modules need to be installed respectively. The output tree
307                   is represented as a recursive tuple of:
308
309                     [ distribution, dependencies ]
310
311                   and the container is an array containing the root elements.
312                   Note that there may be multiple root nodes, since you can
313                   give multiple modules to the "--scandeps" command.
314
315           dists   "dists" is a special output format, where it prints the
316                   distribution filename in the depth first order after the
317                   dependency resolution, like:
318
319                     GAAS/MIME-Base64-3.13.tar.gz
320                     GAAS/URI-1.58.tar.gz
321                     PETDANCE/HTML-Tagset-3.20.tar.gz
322                     GAAS/HTML-Parser-3.68.tar.gz
323                     GAAS/libwww-perl-5.837.tar.gz
324
325                   which means you can install these distributions in this
326                   order without extra dependencies. When combined with "-L"
327                   option, it will be useful to replay installations on other
328                   machines.
329
330       --save-dists
331           Specifies the optional directory path to copy downloaded tarballs
332           in the CPAN mirror compatible directory structure i.e.
333           authors/id/A/AU/AUTHORS/Foo-Bar-version.tar.gz
334
335           If the distro tarball did not come from CPAN, for example from a
336           local file or from GitHub, then it will be saved under
337           vendor/Foo-Bar-version.tar.gz.
338
339       --uninst-shadows
340           Uninstalls the shadow files of the distribution that you're
341           installing. This eliminates the confusion if you're trying to
342           install core (dual-life) modules from CPAN against perl 5.10 or
343           older, or modules that used to be XS-based but switched to pure
344           perl at some version.
345
346           If you run cpanm as root and use "INSTALL_BASE" or equivalent to
347           specify custom installation path, you SHOULD disable this option so
348           you won't accidentally uninstall dual-life modules from the core
349           include path.
350
351           Defaults to true if your perl version is smaller than 5.12, and you
352           can disable that with "--no-uninst-shadows".
353
354           NOTE: Since version 1.3000 this flag is turned off by default for
355           perl newer than 5.12, since with 5.12 @INC contains site_perl
356           directory before the perl core library path, and uninstalling
357           shadows is not necessary anymore and does more harm by deleting
358           files from the core library path.
359
360       --uninstall, -U
361           Uninstalls a module from the library path. It finds a packlist for
362           given modules, and removes all the files included in the same
363           distribution.
364
365           If you enable local::lib, it only removes files from the local::lib
366           directory.
367
368           If you try to uninstall a module in "perl" directory (i.e. core
369           module), an error will be thrown.
370
371           A dialog wil be prompted to confirm the files to be deleted. If you
372           pass "-f" option as well, the dialog will be skipped and
373           uninstallation will be forced.
374
375       --cascade-search
376           EXPERIMENTAL: Specifies whether to cascade search when you specify
377           multiple mirrors and a mirror doesn't have a module or has a lower
378           version of the module than requested. Defaults to false.
379
380       --skip-installed
381           Specifies whether a module given in the command line is skipped if
382           its latest version is already installed. Defaults to true.
383
384           NOTE: The "PERL5LIB" environment variable have to be correctly set
385           for this to work with modules installed using local::lib, unless
386           you always use the "-l" option.
387
388       --skip-satisfied
389           EXPERIMENTAL: Specifies whether a module (and version) given in the
390           command line is skipped if it's already installed.
391
392           If you run:
393
394             cpanm --skip-satisfied CGI DBI~1.2
395
396           cpanm won't install them if you already have CGI (for whatever
397           versions) or have DBI with version higher than 1.2. It is similar
398           to "--skip-installed" but while "--skip-installed" checks if the
399           latest version of CPAN is installed, "--skip-satisfied" checks if a
400           requested version (or not, which means any version) is installed.
401
402           Defaults to false.
403
404       --verify
405           Verify the integrity of distribution files retrieved from PAUSE
406           using CHECKSUMS and SIGNATURES (if found). Defaults to false.
407
408       --report-perl-version
409           Whether it report the locally installed perl version to the various
410           web server as part of User-Agent. Defaults to true, and you can
411           disable it by using "--no-report-perl-version".
412
413       --auto-cleanup
414           Specifies the number of days in which cpanm's work directories
415           expire. Defaults to 7, which means old work directories will be
416           cleaned up in one week.
417
418           You can set the value to 0 to make cpan never cleanup those
419           directories.
420
421       --man-pages
422           Generates man pages for executables (man1) and libraries (man3).
423
424           Defaults to true (man pages generated) unless
425           "-L|--local-lib-contained" option is supplied in which case it's
426           set to false. You can disable it with "--no-man-pages".
427
428       --lwp
429           Uses LWP module to download stuff over HTTP. Defaults to true, and
430           you can say "--no-lwp" to disable using LWP, when you want to
431           upgrade LWP from CPAN on some broken perl systems.
432
433       --wget
434           Uses GNU Wget (if available) to download stuff. Defaults to true,
435           and you can say "--no-wget" to disable using Wget (versions of Wget
436           older than 1.9 don't support the "--retry-connrefused" option used
437           by cpanm).
438
439       --curl
440           Uses cURL (if available) to download stuff. Defaults to true, and
441           you can say "--no-curl" to disable using cURL.
442
443           Normally with "--lwp", "--wget" and "--curl" options set to true
444           (which is the default) cpanm tries LWP, Wget, cURL and HTTP::Tiny
445           (in that order) and uses the first one available.
446

SEE ALSO

448       App::cpanminus
449
451       Copyright 2010 Tatsuhiko Miyagawa.
452

AUTHOR

454       Tatsuhiko Miyagawa
455
456
457
458perl v5.16.3                      2013-06-19                          CPANM(1)
Impressum