cpan

Install a module (-i is optional)

$ cpan [-i] [module_name]

$ cpan -fi [module_name]

$ cpan -u

$ cpan -r

cpan [options] [module_name...]
cpan [shell_command]

-i, --install
    Installs the specified module(s). This is often implicit when a module name is provided.

-f, --force
    Forces the installation even if tests fail or if the module is already installed. Use with caution.

-D, --distinfo
    Displays detailed distribution information for the specified module.

-l, --local-lib
    Configures and uses local::lib for installing modules into a user's home directory without root privileges.

-r, --reinstall
    Reinstalls the specified module(s), even if they appear up-to-date.

-g, --get
    Only downloads the module distribution; does not build or install.

--showdeps
    Shows dependencies for a given module without installing it.

--test
    Runs tests for a module without installing it.

--interactive
    Forces interactive prompts during installation, even if typically non-interactive.

--notest, --skiptest
    Skips running tests for a module during installation. Not recommended unless you know the module is stable.

-a, --autobundle
    Generates a bundle (a list of installed modules) of all currently installed modules that are not part of the standard Perl distribution.

-h, --help
    Displays a short help message and exits.

-v, --version
    Displays the version of the CPAN.pm module and exits.

The cpan command provides a command-line interface to the Comprehensive Perl Archive Network (CPAN), the central repository for Perl modules. It is the primary tool for installing, testing, and managing Perl modules and their dependencies.

When invoked, cpan can either drop the user into an interactive shell for more complex operations (like install Module::Name, test Module::Name, look Module::Name) or execute a single command directly from the command line (e.g., cpan Module::Name to install).

cpan automates the entire module installation process, which typically involves downloading the module source, unpacking it, running its Makefile.PL or Build.PL to generate build scripts, compiling C/XS code if present, running tests, and finally installing the module into the Perl library path. It intelligently resolves and downloads dependencies, ensuring that all required modules are present. This greatly simplifies module management for Perl developers and system administrators, making it easy to leverage the vast ecosystem of reusable Perl code. It is an essential utility for anyone working with Perl.

• Internet Connection Required: cpan needs an active internet connection to download modules from the CPAN mirrors.
• Dependency Resolution: While cpan attempts to resolve and install dependencies, complex dependency chains or conflicts can sometimes lead to failures.
• Root Privileges: Installing modules system-wide often requires root privileges. Using local::lib (cpan -l or configuring local::lib separately) is recommended for user-specific installations without sudo.
• Test Failures: Module tests can sometimes fail due to environment specifics or minor incompatibilities, even if the module itself is functional. The --force option can be used in such cases, but use it judiciously.
• Initial Configuration: The first time cpan is run, it often prompts for configuration, including mirror selection and preferred build tools. This initial setup can be daunting for new users.

When cpan is run without any arguments, it enters an interactive shell (e.g., cpan>). This shell provides commands like install, test, look, search, i, m, o conf, q, etc., offering more control than single-line invocations.

The cpan utility is highly configurable. Users can adjust settings for mirrors, build tools, proxy settings, and installation paths using the o conf command within the interactive shell. Running cpan o conf init will guide a user through the initial setup process.

For users who do not have root access or prefer to keep their Perl modules separate from the system-wide installation, cpan integrates seamlessly with local::lib. Running cpan -l or setting up local::lib environment variables allows modules to be installed into a user's home directory.

The Comprehensive Perl Archive Network (CPAN) was founded in 1995 by Jarkko Hietaniemi. It quickly became the definitive repository for Perl modules, revolutionizing how Perl developers share and reuse code. The CPAN.pm module, which the cpan command-line utility wraps, was developed to provide an interactive interface to this vast archive. Over the years, cpan has evolved significantly, adding features for dependency management, testing, and configuration. Its development has been driven by the Perl community, continuously adapting to new Perl versions and ecosystem needs. It remains an indispensable tool, central to the Perl development workflow, enabling rapid development by providing access to tens of thousands of pre-built solutions.

perl(1), perlmod(1), perldoc(1), make(1), tar(1)