App::cpm::Tutorial(3pm) User Contributed Perl Documentation App::cpm::Tutorial(3pm)

# [NAME](#NAME)

App::cpm::Tutorial - How to use cpm

# [SYNOPSIS](#SYNOPSIS)

```
  $ cpm install Module
```

# [DESCRIPTION](#DESCRIPTION)

cpm is yet another CPAN client (like cpan, cpanp, and cpanm), which is fast!

## [How to install cpm](#How_to_install_cpm)

Download the latest self-contained cpm and run it directly:

```
  curl -fsSL -o cpm https://github.com/skaji/cpm/releases/latest/download/cpm &&
    chmod +x cpm &&
    ./cpm --version
```

To verify its artifact attestation before running it, use this sequence instead. It requires the GitHub CLI <https://cli.github.com/> ("gh") and stops if downloading or verification fails:

```
  curl -fsSL -o cpm https://github.com/skaji/cpm/releases/latest/download/cpm &&
    gh attestation verify cpm --repo skaji/cpm &&
    chmod +x cpm &&
    ./cpm --version
```

You can use "./cpm" as is, or place it in a directory on your "PATH".

## [First step](#First_step)

```
  $ cpm install Plack
```

This command installs Plack into "./local", and you can use it by

```
  $ perl -I$PWD/local/lib/perl5 -MPlack -E 'say Plack->VERSION'
```

By default, cpm installs the requested distributions and their runtime dependency closure.

If you want to install modules into current INC instead of "./local", then use "--global/-g" option.

```
  $ cpm install --global Plack
```

By default, cpm chooses a progress mode automatically. On interactive terminals, it usually shows the terminal progress UI. Otherwise, it uses plain line-by-line output.

If you want plain output explicitly, use "--progress=plain". If you want more verbose messages, use "--verbose/-v" option.

```
  $ cpm install --progress=plain Plack
  $ cpm install --verbose Plack
```

## [Second step](#Second_step)

cpm can handle version range notation like cpanm. Let's see some examples.

```
  $ cpm install Plack~'> 1.000, <= 2.000'
  $ cpm install Plack~'== 1.0030'
  $ cpm install Plack@1.0030  # this is an alias of ~'== 1.0030'
```

cpm can install dev releases (TRIAL releases).

```
  $ cpm install Moose@dev
  # if you prefer dev releases for not only Moose,
  # but also its dependencies, then use global --dev option
  $ cpm install --dev Moose
```

And cpm can install modules from git repositories directly.

```
  $ cpm install https://github.com/skaji/Carl.git
```

## [cpanfile and dist/url/mirror/git syntax](#cpanfile_and_dist/url/mirror/git_syntax)

If you omit arguments, and there exists one of

[cpm.yml &lt;https://metacpan.org/pod/Module::cpmfile&gt;](#cpm.yml)

[cpanfile &lt;https://metacpan.org/dist/Module-CPANfile/view/lib/cpanfile.pod&gt;](#cpanfile)

[META.json &lt;https://metacpan.org/pod/CPAN::Meta::Spec&gt; (with dynamic\_config false)](#META.json)

"Build.PL"

"Makefile.PL"

in the current directory, then cpm loads modules from the file, and install them

```
  $ cat cpanfile
  requires 'Moose', '2.000';
  requires 'Plack', '> 1.000, <= 2.000';
  $ cpm install
```

By default, cpm reads the "configure", "build", "test", "runtime", and "develop" phases from the top-level dependency file.

If you want to select phases or relationships explicitly, use "--top-level-phase" and "--top-level-relationship".

```
  $ cpm install --top-level-phase runtime
  $ cpm install --top-level-relationship requires,recommends
```

If you have "cpanfile.snapshot", then cpm tries to resolve distribution names from it

```
  $ cpm install -v
  30186 DONE resolve (0.001sec) Plack -> Plack-1.0030 (from Snapshot)
  ...
```

cpm supports dist/url/mirror syntax in cpanfile just like cpanminus:

```
  requires 'Path::Class', 0.26,
    dist => "KWILLIAMS/Path-Class-0.26.tar.gz";
  # use dist + mirror
  requires 'Cookie::Baker',
    dist => "KAZEBURO/Cookie-Baker-0.08.tar.gz",
    mirror => "http://cpan.cpantesters.org/";
  # use the full URL
  requires 'Try::Tiny', 0.28,
    url => "http://backpan.perl.org/authors/id/E/ET/ETHER/Try-Tiny-0.28.tar.gz";
```

cpm also supports git syntax in cpanfile:

```
  requires 'Carl', git => 'https://github.com/skaji/Carl.git';
  requires 'App::cpm', git => 'https://login:password@github.com/skaji/cpm.git';
  requires 'Perl::PrereqDistributionGatherer',
    git => 'https://github.com/skaji/Perl-PrereqDistributionGatherer',
    ref => '3850305'; # ref can be revision/branch/tag
```

Please note that to support git syntax in cpanfile wholly, there are several TODOs.

## [Darkpan integration](#Darkpan_integration)

There are CPAN modules that create *darkpans* (minicpan, CPAN mirror) such as CPAN::Mini, OrePAN2, Pinto.

Such darkpans store distribution tarballs in

```
  DARKPAN/authors/id/A/AU/AUTHOR/Module-0.01.tar.gz
```

and create the *de facto standard* index file "02packages.details.txt.gz" in

```
  DARKPAN/modules/02packages.details.txt.gz
```

If you want to use cpm against such darkpans, change the cpm resolver by "--resolver/-r" option:

```
  $ cpm install --resolver 02packages,http://example.com/darkpan Module
  $ cpm install --resolver 02packages,file::///path/to/darkpan   Module
```

If you host your own metadb for your own darkpan, you can use it too:

```
  $ cpm install \
     --resolver metadb,http://example.com/darkmetadb,http://example.com/darkpan \
     Module
```

2026-10-22 perl v5.44.0

---

Document: App::cpm::Tutorial(3pm) from perl-app-cpm 1.1.6-r0 (Chainguard OS)
Source: https://github.com/skaji/cpm