.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.15)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CPANM 1"
.TH CPANM 1 "2013-01-31" "perl v5.10.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
cpanm \- get, unpack build and install modules from CPAN
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\&  cpanm Test::More                                 # install Test::More
\&  cpanm MIYAGAWA/Plack\-0.99_05.tar.gz              # full distribution path
\&  cpanm http://example.org/LDS/CGI.pm\-3.20.tar.gz  # install from URL
\&  cpanm ~/dists/MyCompany\-Enterprise\-1.00.tar.gz   # install from a local file
\&  cpanm \-\-interactive Task::Kensho                 # Configure interactively
\&  cpanm .                                          # install from local directory
\&  cpanm \-\-installdeps .                            # install all the deps for the current directory
\&  cpanm \-L extlib Plack                            # install Plack and all non\-core deps into extlib
\&  cpanm \-\-mirror http://cpan.cpantesters.org/ DBI  # use the fast\-syncing mirror
\&  cpanm \-\-scandeps Moose                           # See what modules will be installed for Moose
.Ve
.SH "COMMANDS"
.IX Header "COMMANDS"
.IP "\-i, \-\-install" 4
.IX Item "-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.
.IP "\-\-self\-upgrade" 4
.IX Item "--self-upgrade"
Upgrades itself. It's just an alias for:
.Sp
.Vb 1
\&  cpanm App::cpanminus
.Ve
.IP "\-\-info" 4
.IX Item "--info"
Displays the distribution information in
\&\f(CW\*(C`AUTHOR/Dist\-Name\-ver.tar.gz\*(C'\fR format in the standard out.
.IP "\-\-installdeps" 4
.IX Item "--installdeps"
Installs the dependencies of the target distribution but won't build
itself. Handy if you want to try the application from a version
controlled repository such as git.
.Sp
.Vb 1
\&  cpanm \-\-installdeps .
.Ve
.IP "\-\-look" 4
.IX Item "--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.
.IP "\-h, \-\-help" 4
.IX Item "-h, --help"
Displays the help message.
.IP "\-V, \-\-version" 4
.IX Item "-V, --version"
Displays the version number.
.SH "OPTIONS"
.IX Header "OPTIONS"
You can specify the default options in \f(CW\*(C`PERL_CPANM_OPT\*(C'\fR environment variable.
.IP "\-f, \-\-force" 4
.IX Item "-f, --force"
Force install modules even when testing failed.
.IP "\-n, \-\-notest" 4
.IX Item "-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 you've already tested to make sure it builds fine.
.Sp
Defaults to false, and you can say \f(CW\*(C`\-\-no\-notest\*(C'\fR to override when it
is set in the default options in \f(CW\*(C`PERL_CPANM_OPT\*(C'\fR.
.IP "\-\-test\-only" 4
.IX Item "--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.
.Sp
Note that if you specify this option with a module or distribution
that has dependencies, these dependencies will be installed if you
don't currently have them.
.IP "\-S, \-\-sudo" 4
.IX Item "-S, --sudo"
Switch to the root user with \f(CW\*(C`sudo\*(C'\fR when installing modules. Use this
if you want to install modules to the system perl include path.
.Sp
Defaults to false, and you can say \f(CW\*(C`\-\-no\-sudo\*(C'\fR to override when it is
set in the default options in \f(CW\*(C`PERL_CPANM_OPT\*(C'\fR.
.IP "\-v, \-\-verbose" 4
.IX Item "-v, --verbose"
Makes the output verbose. It also enables the interactive
configuration. (See \-\-interactive)
.IP "\-q, \-\-quiet" 4
.IX Item "-q, --quiet"
Makes the output even more quiet than the default. It doesn't print
anything to the \s-1STDERR\s0.
.IP "\-l, \-\-local\-lib" 4
.IX Item "-l, --local-lib"
Sets the local::lib compatible path to install modules to. You
don't 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.
.IP "\-L, \-\-local\-lib\-contained" 4
.IX Item "-L, --local-lib-contained"
Same with \f(CW\*(C`\-\-local\-lib\*(C'\fR but when examining the dependencies, it
assumes no non-core modules are installed on the system. It's handy if
you want to bundle application dependencies in one directory so you
can distribute to other machines.
.Sp
For instance,
.Sp
.Vb 1
\&  cpanm \-L extlib Plack
.Ve
.Sp
would install Plack and all of its non-core dependencies into the
directory \f(CW\*(C`extlib\*(C'\fR, which can be loaded from your application with:
.Sp
.Vb 1
\&  use local::lib \*(Aq/path/to/extlib\*(Aq;
.Ve
.IP "\-\-mirror" 4
.IX Item "--mirror"
Specifies the base \s-1URL\s0 for the \s-1CPAN\s0 mirror to use, such as
\&\f(CW\*(C`http://cpan.cpantesters.org/\*(C'\fR (you can omit the trailing slash). You
can specify multiple mirror URLs by repeating the command line option.
.Sp
You can use a local directory that has a \s-1CPAN\s0 mirror structure
(created by tools such as OrePAN or Pinto) by using a special
\&\s-1URL\s0 scheme \f(CW\*(C`file://\*(C'\fR. If the given \s-1URL\s0 begins with `/` (without any
scheme), it is considered as a file scheme as well.
.Sp
.Vb 2
\&  cpanm \-\-mirror file:///path/to/mirror
\&  cpanm \-\-mirror ~/minicpan      # Because shell expands ~ to /home/user
.Ve
.Sp
Defaults to \f(CW\*(C`http://search.cpan.org/CPAN\*(C'\fR which is a geo location
aware redirector.
.IP "\-\-mirror\-only" 4
.IX Item "--mirror-only"
Download the mirror's 02packages.details.txt.gz index file instead of
querying the \s-1CPAN\s0 Meta \s-1DB\s0.
.Sp
Select this option if you are using a local mirror of \s-1CPAN\s0, such as
minicpan when you're offline, or your own \s-1CPAN\s0 index (a.k.a darkpan).
.Sp
\&\fBTip:\fR It might be useful if you name these mirror options with your
shell aliases, like:
.Sp
.Vb 2
\&  alias minicpanm=\*(Aqcpanm \-\-mirror ~/minicpan \-\-mirror\-only\*(Aq
\&  alias darkpan=\*(Aqcpanm \-\-mirror http://mycompany.example.com/DPAN \-\-mirror\-only\*(Aq
.Ve
.IP "\-\-mirror\-index" 4
.IX Item "--mirror-index"
\&\fB\s-1EXPERIMENTAL\s0\fR: Specifies the file path to \f(CW\*(C`02packages.details.txt\*(C'\fR
for module search index.
.IP "\-\-metacpan" 4
.IX Item "--metacpan"
\&\fB\s-1EXPERIMENTAL\s0\fR: Use <http://api.metacpan.org/> \s-1API\s0 for module lookup instead of
<http://cpanmetadb.plackperl.org/>.
.IP "\-\-prompt" 4
.IX Item "--prompt"
Prompts when a test fails so that you can skip, force install, retry
or look in the shell to see what's going wrong. It also prompts when
one of the dependency failed if you want to proceed the installation.
.Sp
Defaults to false, and you can say \f(CW\*(C`\-\-no\-prompt\*(C'\fR to override if it's
set in the default options in \f(CW\*(C`PERL_CPANM_OPT\*(C'\fR.
.IP "\-\-reinstall" 4
.IX Item "--reinstall"
cpanm, when given a module name in the command line (i.e. \f(CW\*(C`cpanm
Plack\*(C'\fR), checks the locally installed version first and skips if it is
already installed. This option makes it skip the check, so:
.Sp
.Vb 1
\&  cpanm \-\-reinstall Plack
.Ve
.Sp
would reinstall Plack even if your locally installed version is
latest, or even newer (which would happen if you install a developer
release from version control repositories).
.Sp
Defaults to false.
.IP "\-\-interactive" 4
.IX Item "--interactive"
Makes the configuration (such as \f(CW\*(C`Makefile.PL\*(C'\fR and \f(CW\*(C`Build.PL\*(C'\fR)
interactive, so you can answer questions in the distribution that
requires custom configuration or Task:: distributions.
.Sp
Defaults to false, and you can say \f(CW\*(C`\-\-no\-interactive\*(C'\fR to override
when it's set in the default options in \f(CW\*(C`PERL_CPANM_OPT\*(C'\fR.
.IP "\-\-scandeps" 4
.IX Item "--scandeps"
Scans the depencencies of given modules and output the tree in a text
format. (See \f(CW\*(C`\-\-format\*(C'\fR below for more options)
.Sp
Because this command doesn't actually install any distributions, it
will be useful that by typing:
.Sp
.Vb 1
\&  cpanm \-\-scandeps Catalyst::Runtime
.Ve
.Sp
you can make sure what modules will be installed.
.Sp
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 \f(CW\*(C`\-L\*(C'\fR option.
.IP "\-\-format" 4
.IX Item "--format"
Determines what format to display the scanned dependency
tree. Available options are \f(CW\*(C`tree\*(C'\fR, \f(CW\*(C`json\*(C'\fR, \f(CW\*(C`yaml\*(C'\fR and \f(CW\*(C`dists\*(C'\fR.
.RS 4
.IP "tree" 8
.IX Item "tree"
Displays the tree in a plain text format. This is the default value.
.IP "json, yaml" 8
.IX Item "json, yaml"
Outputs the tree in a \s-1JSON\s0 or \s-1YAML\s0 format. \s-1JSON\s0 and \s-1YAML\s0 modules
need to be installed respectively. The output tree is represented as a
recursive tuple of:
.Sp
.Vb 1
\&  [ distribution, dependencies ]
.Ve
.Sp
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 \f(CW\*(C`\-\-scandeps\*(C'\fR command.
.IP "dists" 8
.IX Item "dists"
\&\f(CW\*(C`dists\*(C'\fR is a special output format, where it prints the distribution
filename in the \fIdepth first order\fR after the dependency resolution,
like:
.Sp
.Vb 5
\&  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
.Ve
.Sp
which means you can install these distributions in this order without
extra dependencies. When combined with \f(CW\*(C`\-L\*(C'\fR option, it will be useful
to replay installations on other machines.
.RE
.RS 4
.RE
.IP "\-\-save\-dists" 4
.IX Item "--save-dists"
Specifies the optional directory path to copy downloaded tarballs in
the \s-1CPAN\s0 mirror compatible directory structure
i.e. \fIauthors/id/A/AU/AUTHORS/Foo\-Bar\-version.tar.gz\fR
.IP "\-\-uninst\-shadows" 4
.IX Item "--uninst-shadows"
Uninstalls the shadow files of the distribution that you're
installing. This eliminates the confusion if you're trying to install
core (dual-life) modules from \s-1CPAN\s0 against perl 5.10 or older, or
modules that used to be XS-based but switched to pure perl at some
version.
.Sp
If you run cpanm as root and use \f(CW\*(C`INSTALL_BASE\*(C'\fR or equivalent to
specify custom installation path, you \s-1SHOULD\s0 disable this option so
you won't accidentally uninstall dual-life modules from the core
include path.
.Sp
Defaults to true if your perl version is smaller than 5.12, and you
can disable that with \f(CW\*(C`\-\-no\-uninst\-shadows\*(C'\fR.
.Sp
\&\fB\s-1NOTE\s0\fR: Since version 1.3000 this flag is turned off by default for
perl newer than 5.12, since with 5.12 \f(CW@INC\fR contains site_perl directory
\&\fIbefore\fR the perl core library path, and uninstalling shadows is not
necessary anymore and does more harm by deleting files from the core
library path.
.IP "\-\-cascade\-search" 4
.IX Item "--cascade-search"
\&\fB\s-1EXPERIMENTAL\s0\fR: Specifies whether to cascade search when you specify
multiple mirrors and a mirror doesn't have a module or has a lower
version of the module than requested. Defaults to false.
.IP "\-\-skip\-installed" 4
.IX Item "--skip-installed"
Specifies whether a module given in the command line is skipped if its latest
version is already installed. Defaults to true.
.Sp
\&\fB\s-1NOTE\s0\fR: The \f(CW\*(C`PERL5LIB\*(C'\fR environment variable have to be correctly set for this
to work with modules installed using local::lib.
.IP "\-\-skip\-satisfied" 4
.IX Item "--skip-satisfied"
\&\fB\s-1EXPERIMENTAL\s0\fR: Specifies whether a module (and version) given in the
command line is skipped if it's already installed.
.Sp
If you run:
.Sp
.Vb 1
\&  cpanm \-\-skip\-satisfied CGI DBI~1.2
.Ve
.Sp
cpanm won't install them if you already have \s-1CGI\s0 (for whatever
versions) or have \s-1DBI\s0 with version higher than 1.2. It is similar to
\&\f(CW\*(C`\-\-skip\-installed\*(C'\fR but while \f(CW\*(C`\-\-skip\-installed\*(C'\fR checks if the
\&\fIlatest\fR version of \s-1CPAN\s0 is installed, \f(CW\*(C`\-\-skip\-satisfied\*(C'\fR checks if
a requested version (or not, which means any version) is installed.
.Sp
Defaults to false for bare module names, but if you specify versions
with \f(CW\*(C`~\*(C'\fR, it will always skip satisfied requirements.
.IP "\-\-verify" 4
.IX Item "--verify"
Verify the integrity of distribution files retrieved from \s-1PAUSE\s0 using
\&\s-1CHECKSUMS\s0 and \s-1SIGNATURES\s0 (if found). Defaults to false.
.IP "\-\-auto\-cleanup" 4
.IX Item "--auto-cleanup"
Specifies the number of days in which cpanm's work directories
expire. Defaults to 7, which means old work directories will be
cleaned up in one week.
.Sp
You can set the value to \f(CW0\fR to make cpan never cleanup those
directories.
.IP "\-\-man\-pages" 4
.IX Item "--man-pages"
Generates man pages for executables (man1) and libraries (man3).
.Sp
Defaults to false (no man pages generated) if
\&\f(CW\*(C`\-L|\-\-local\-lib\-contained\*(C'\fR option is supplied. Otherwise, defaults to
true, and you can disable it with \f(CW\*(C`\-\-no\-man\-pages\*(C'\fR.
.IP "\-\-lwp" 4
.IX Item "--lwp"
Uses \s-1LWP\s0 module to download stuff over \s-1HTTP\s0. Defaults to true, and
you can say \f(CW\*(C`\-\-no\-lwp\*(C'\fR to disable using \s-1LWP\s0, when you want to upgrade
\&\s-1LWP\s0 from \s-1CPAN\s0 on some broken perl systems.
.IP "\-\-wget" 4
.IX Item "--wget"
Uses \s-1GNU\s0 Wget (if available) to download stuff. Defaults to true, and
you can say \f(CW\*(C`\-\-no\-wget\*(C'\fR to disable using Wget (versions of Wget older
than 1.9 don't support the \f(CW\*(C`\-\-retry\-connrefused\*(C'\fR option used by cpanm).
.IP "\-\-curl" 4
.IX Item "--curl"
Uses cURL (if available) to download stuff. Defaults to true, and
you can say \f(CW\*(C`\-\-no\-curl\*(C'\fR to disable using cURL.
.Sp
Normally with \f(CW\*(C`\-\-lwp\*(C'\fR, \f(CW\*(C`\-\-wget\*(C'\fR and \f(CW\*(C`\-\-curl\*(C'\fR options set to true
(which is the default) cpanm tries \s-1LWP\s0, Wget, cURL and HTTP::Tiny
(in that order) and uses the first one available.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
App::cpanminus
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2010 Tatsuhiko Miyagawa.
.SH "AUTHOR"
.IX Header "AUTHOR"
Tatsuhiko Miyagawa