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
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 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 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 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 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 For a git repository, you can specify a branch, tag, or commit SHA
47 to build. The default is "master"
48 cpanm git://github.com/miyagawa/Plack.git@1.0000 # tag
50 cpanm git://github.com/miyagawa/Plack.git@devel # branch
51 -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 --self-upgrade
57 Upgrades itself. It's just an alias for:
58 cpanm App::cpanminus
60 --info
62 Displays the distribution information in
63 "AUTHOR/Dist-Name-ver.tar.gz" format in the standard out.
64 --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 cpanm --installdeps .
71 --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 -U, --uninstall
78 EXPERIMENTAL: Uninstalls the modules. Will remove the distribution
79 files from your library path using the ".packlist" file.
80 When used with "-l" or "-L", only the files under the local::lib
82 directory will be removed.
83 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 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 -h, --help
94 Displays the help message.
95 -V, --version
97 Displays the version number.
98
100 You can specify the default options in "PERL_CPANM_OPT" environment
101 variable.
102 -f, --force
104 Force install modules even when testing failed.
105 -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 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 --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 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 -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 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 -v, --verbose
132 Makes the output verbose. It also enables the interactive
133 configuration. (See --interactive)
134 -q, --quiet
136 Makes the output even more quiet than the default. It only shows
137 the successful/failed dependencies to the output.
138 -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 -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 For instance,
151 cpanm -L extlib Plack
153 would install Plack and all of its non-core dependencies into the
155 directory "extlib", which can be loaded from your application with:
156 use local::lib '/path/to/extlib';
158 --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 --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 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 cpanm --mirror file:///path/to/mirror
177 cpanm --mirror ~/minicpan # Because shell expands ~ to /home/user
178 Defaults to "http://www.cpan.org/".
180 --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 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 Tip: It might be useful if you name these mirror options with your
192 shell aliases, like:
193 alias minicpanm='cpanm --mirror ~/minicpan --mirror-only'
195 alias darkpan='cpanm --mirror http://mycompany.example.com/DPAN --mirror-only'
196 --mirror-index
198 EXPERIMENTAL: Specifies the file path to "02packages.details.txt"
199 for module search index.
200 --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 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 --dev
211 EXPERIMENTAL: search for a newer developer release as well.
212 Defaults to false.
213 --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 cpanm --reinstall Plack
220 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 Defaults to false.
226 --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 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 --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 --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 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 There's also "--without-recommend" and "--without-suggests" to
251 override the default decision made earlier in "PERL_CPANM_OPT".
252 Defaults to false for both.
254 --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 cpanm --with-feature=opt_csv Spreadsheet::Read
260 the features can also be interactively chosen when "--interactive"
262 option is enabled.
263 "--with-all-features" enables all the optional features, and
265 "--without-feature" can select a feature to disable.
266 --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 --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 cpanm DBD::mysql --configure-args="--cflags=... --libs=..."
277 The argument is only enabled for the module passed as a command
279 line argument, not dependencies.
280 --scandeps
282 Scans the depencencies of given modules and output the tree in a
283 text format. (See "--format" below for more options)
284 Because this command doesn't actually install any distributions, it
286 will be useful that by typing:
287 cpanm --scandeps Catalyst::Runtime
289 you can make sure what modules will be installed.
291 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 --format
298 Determines what format to display the scanned dependency tree.
299 Available options are "tree", "json", "yaml" and "dists".
300 tree Displays the tree in a plain text format. This is the
302 default value.
303 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 [ distribution, dependencies ]
310 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 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 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 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 --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 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 --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 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 Defaults to true if your perl version is smaller than 5.12, and you
352 can disable that with "--no-uninst-shadows".
353 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 --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 If you enable local::lib, it only removes files from the local::lib
366 directory.
367 If you try to uninstall a module in "perl" directory (i.e. core
369 module), an error will be thrown.
370 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 --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 --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 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 --skip-satisfied
389 EXPERIMENTAL: Specifies whether a module (and version) given in the
390 command line is skipped if it's already installed.
391 If you run:
393 cpanm --skip-satisfied CGI DBI~1.2
395 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 Defaults to false.
403 --verify
405 Verify the integrity of distribution files retrieved from PAUSE
406 using CHECKSUMS and SIGNATURES (if found). Defaults to false.
407 --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 --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 You can set the value to 0 to make cpan never cleanup those
419 directories.
420 --man-pages
422 Generates man pages for executables (man1) and libraries (man3).
423 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 --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 --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 --curl
440 Uses cURL (if available) to download stuff. Defaults to true, and
441 you can say "--no-curl" to disable using cURL.
442 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
448 App::cpanminus
449
451 Copyright 2010 Tatsuhiko Miyagawa.
452
454 Tatsuhiko Miyagawa
455perl v5.16.3 2013-06-19 CPANM(1)