From Gentoo Wiki
Jump to:navigation Jump to:search
This article is a stub. Please help out by expanding it - how to get started.

CPAN is the Comprehensive Perl Archive Network, Perl's package ecosystem. The original client for the CPAN network was also called cpan, though its use is now relatively uncommon in favor of more modern clients.


The perl-core/CPAN package is installed by default as Perl is a system package.


For most operations there is little to no configuration required to get cpan to work correctly. If cpan fails to fetch packages from CPAN as expected, see the troubleshooting section.

Environment variables

  • NONINTERACTIVE_TESTING — Skip all package prompts.
  • PERL_MM_USE_DEFAULT — Assume the default response for all prompts.
  • CPAN_OPTS — A string of default options to be passed to cpan at runtime.
  • CPANSCRIPT_LOGLEVEL — for use with the system logger.
  • GIT_COMMAND — the path to the git binary. By default this value is /usr/local/bin/git.


For most cases the cpan module is invoked as: cpan <package_name>


user $cmd -h
    cpan - easily interact with CPAN from the command line

            # with arguments and no switches, installs specified modules
            cpan module_name [ module_name ... ]

            # with switches, installs modules with extra behavior
            cpan [-cfFimtTw] module_name [ module_name ... ]

            # use local::lib
            cpan -I module_name [ module_name ... ]

            # one time mirror override for faster mirrors
            cpan -p ...

            # with just the dot, install from the distribution in the
            # current directory
            cpan .

            # without arguments, starts shell

            # without arguments, but some switches
            cpan [-ahpruvACDLOPX]

    This script provides a command interface (not a shell) to CPAN. At the
    moment it uses to do the work, but it is not a one-shot command
    runner for

    -a  Creates a autobundle with CPAN::Shell->autobundle.

    -A module [ module ... ]
        Shows the primary maintainers for the specified modules.

    -c module
        Runs a `make clean` in the specified module's directories.

    -C module [ module ... ]
        Show the Changes files for the specified modules

    -D module [ module ... ]
        Show the module details. This prints one line for each out-of-date
        module (meaning, modules locally installed but have newer versions
        on CPAN). Each line has three columns: module name, local version,
        and CPAN version.

    -f  Force the specified action, when it normally would have failed. Use
        this to install a module even if its tests fail. When you use this
        option, -i is not optional for installing a module when you need to
        force it:

                % cpan -f -i Module::Foo

    -F  Turn off's attempts to lock anything. You should be careful
        with this since you might end up with multiple scripts trying to
        muck in the same directory. This isn't so much of a concern if
        you're loading a special config with "-j", and that config sets up
        its own work directories.

    -g module [ module ... ]
        Downloads to the current directory the latest distribution of the

    -G module [ module ... ]

        Download to the current directory the latest distribution of the
        modules, unpack each distribution, and create a git repository for
        each distribution.

        If you want this feature, check out Yanick Champoux's
        "Git::CPAN::Patch" distribution.

    -h  Print a help message and exit. When you specify "-h", it ignores all
        of the other options and arguments.

    -i module [ module ... ]
        Install the specified modules. With no other switches, this switch
        is implied.

    -I  Load "local::lib" (think like "-I" for loading lib paths). Too bad
        "-l" was already taken.

        Load the file that has the CPAN configuration data. This should have
        the same format as the standard CPAN/ file, which defines
        $CPAN::Config as an anonymous hash.

    -J  Dump the configuration in the same format that uses. This is
        useful for checking the configuration as well as using the dump as a
        starting point for a new, custom configuration.

    -l  List all installed modules with their versions

    -L author [ author ... ]
        List the modules by the specified authors.

    -m  Make the specified modules.

    -M mirror1,mirror2,...
        A comma-separated list of mirrors to use for just this run. The "-P"
        option can find them for you automatically.

    -n  Do a dry run, but don't actually install anything. (unimplemented)

    -O  Show the out-of-date modules.

    -p  Ping the configured mirrors and print a report

    -P  Find the best mirrors you could be using and use them for the
        current session.

    -r  Recompiles dynamically loaded modules with CPAN::Shell->recompile.

    -s  Drop in the shell. This command does this automatically if
        you don't specify any arguments.

    -t module [ module ... ]
        Run a `make test` on the specified modules.

    -T  Do not test modules. Simply install them.

    -u  Upgrade all installed modules. Blindly doing this can really break
        things, so keep a backup.

    -v  Print the script version and version then exit.

    -V  Print detailed information about the cpan client.


        Turn on cpan warnings. This checks various things, like directory
        permissions, and tells you about problems you might have.

    -x module [ module ... ]
        Find close matches to the named modules that you think you might
        have mistyped. This requires the optional installation of
        Text::Levenshtein or Text::Levenshtein::Damerau.

    -X  Dump all the namespaces to standard output.

            # print a help message
            cpan -h

            # print the version numbers
            cpan -v

            # create an autobundle
            cpan -a

            # recompile modules
            cpan -r

            # upgrade all installed modules
            cpan -u

            # install modules ( sole -i is optional )
            cpan -i Netscape::Booksmarks Business::ISBN

            # force install modules ( must use -i )
            cpan -fi CGI::Minimal URI

            # install modules but without testing them
            cpan -Ti CGI::Minimal URI

  Environment variables
    There are several components in that use environment variables.
    The build tools, ExtUtils::MakeMaker and Module::Build use some, while
    others matter to the levels above them. Some of these are specified by
    the Perl Toolchain Gang:

    Lancaster Consensus:

    Oslo Consensus:

        Assume no one is paying attention and skips prompts for
        distributions that do that correctly. cpan(1) sets this to 1 unless
        it already has a value (even if that value is false).

        Use the default answer for a prompted questions. cpan(1) sets this
        to 1 unless it already has a value (even if that value is false).

        As with "PERL5OPT", a string of additional cpan(1) options to add to
        those you specify on the command line.

        The log level to use, with either the embedded, minimal logger or
        Log::Log4perl if it is installed. Possible values are the same as
        the "Log::Log4perl" levels: "TRACE", "DEBUG", "INFO", "WARN",
        "ERROR", and "FATAL". The default is "INFO".

        The path to the "git" binary to use for the Git features. The
        default is "/usr/local/bin/git".

    The script exits with zero if it thinks that everything worked, or a
    positive number if it thinks that something failed. Note, however, that
    in some cases it has to divine a failure by the output of things it does
    not control. For now, the exit codes are vague:

            1       An unknown error

            2       The was an external problem

            4       There was an internal problem with the script

            8       A module failed to install

    * one shot configuration values from the command line

    * none noted

    Most behaviour, including environment variables and configuration, comes
    directly from

    This code is in Github in the repository:


    The source used to be tracked separately in another GitHub repo, but the
    canonical source is now in the above repo.

    Japheth Cleaver added the bits to allow a forced install (-f).

    Jim Brandt suggest and provided the initial implementation for the
    up-to-date and Changes features.

    Adam Kennedy pointed out that exit() causes problems on Windows where
    this script ends up with a .bat extension

    brian d foy, "<>"

    Copyright (c) 2001-2015, brian d foy, All Rights Reserved.

    You may redistribute this under the same terms as Perl itself.


Lack of TLS Support

The original CPAN client cpan is limited to http and ftp only. For most users this fact will not impact functionality. See the Troubleshooting section if this causes issues.



Access to the CPAN package network is blocked by a corporate firewall

Modern corporate environments now routinely block unencrypted traffic. Unfortunately the original CPAN Network client cpan lacks support for TLS, all traffic is http and ftp only.

The solution is to use a more modern CPAN Network client such as dev-perl/App-cpanminus. This CPAN client fully supports accessing the CPAN network over https.

See also

  • Application level package management — provides best practice recommendations on managing the coexistence of operating system and application level package managers on Gentoo.
  • Gem — programs and libraries for the Ruby programming language.
  • Perl — a general purpose interpreted programming language with a powerful regular expression engine.
  • PipPython's package management system. It references packages available in the official Python Package Index (PyPI).
  • Portage — the official package manager and distribution system for Gentoo.