Manage CPAN modules with cpanminus

puppet module install jamesmcdonald-cpanm --version 0.9.10



Table of Contents

  1. Description
  2. Setup - The basics of getting started with cpanm
  3. Usage - Configuration options and additional functionality
  4. Reference - An under-the-hood peek at what the module is doing and how
  5. Limitations - OS compatibility, etc.
  6. Development - Guide for contributing to the module


The cpanm module manages CPAN packages using the cpanminus package. It exists to provide a simple way to install CPAN modules with the option to not run test suites. The intent is that it should work with Debianish and Redhatty distributions.

The module provides a class cpanm which will install Perl components, gcc, make and cpanminus itself. It also provides a resource type cpanm which you can use to manage modules in more or less the same way as package works.


What cpanm affects

This module will currently automatically install the following packages:

  • perl
  • gcc
  • make
  • perl-core on RHEL6-7

These are installed using ensure_packages, so shouldn't cause conflicts if you have them managed elsewhere.

It will also install cpanm itself in a standard directory, generally /usr/bin or /usr/local/bin and a copy of cpanm used for bootstrapping in /var/cache/cpanm-install.

Setup Requirements

This module contains a custom type, so you must make sure pluginsync is enabled if you are using a puppet master.

Beginning with cpanm

include cpanm

cpanm {'CGI':
  ensure => latest,


Both the cpanm class and resource support a mirror parameter to control which CPAN archive packages are fetched from. The cpanm resource supports additional parameters, test and force, to enable CPAN tests and force CPAN installation respectively.


The cpanm class currently supports one parameter:

  • mirror A CPAN mirror to use to retrieve App::cpanminus. This is passed to cpanm as --from, meaning that only this mirror will be used.

  • lwpbootstrap Option to pass --no-lwp in the bootstrap command. Default: false.

The cpanm resource supports:

  • ensure absent, present or latest.

  • force Pass the '-f' (force) option to CPAN installation. Boolean, default is false. This only has an effect on installation or upgrade. It does nothing unless the value of ensure causes a change to be made.

  • mirror A CPAN mirror to use to retrieve packages. This is passed to cpanm as --from, meaning that only this mirror will be used.

  • test Run CPAN tests. Boolean, default is false.

The module contains a copy of cpanminus, which is used to bootstrap installing itself.


The module is tested on RHEL 5-7 and Debian Jessie and Stretch. It should work properly in those environments, but it is relatively simple, so it may well work in similar environments without modification. If you need specific changes for your environment, feel free to send them!

Known Issues

The listing of installed CPAN modules is based on perldoc perllocal. This generally works well, but doesn't get updated when you remove a CPAN module.


If you make improvements or fixes, please feel free to send a PR on Github. This module exists to solve a specific problem for me, but I'm quite happy to extend it to support other people's use cases.


This module contains a copy of cpanminus retrieved from https://cpanmin.us. App::cpanminus is written by Tatsuhiko Miyagawa and distributed under the same terms as Perl. You can read more details about contributors via the link.