The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.


BackPAN::Index - An interface to the BackPAN index


    use BackPAN::Index;
    my $backpan = BackPAN::Index->new;

    # These are all DBIx::Class::ResultSet's
    my $files    = $backpan->files;
    my $dists    = $backpan->dists;
    my $releases = $backpan->releases("Acme-Pony");

    # Use DBIx::Class::ResultSet methods on them
    my $release = $releases->single({ version => '1.23' });

    my $dist = $backpan->dist("Test-Simple");
    my $releases = $dist->releases;


This downloads, caches and parses the BackPAN index into a local database for efficient querying.

Its a pretty thin wrapper around DBIx::Class returning DBIx::Class::ResultSet objects which makes it efficient and flexible.

The Comprehensive Perl Archive Network (CPAN) is a very useful collection of Perl code. However, in order to keep CPAN relatively small, authors of modules can delete older versions of modules to only let CPAN have the latest version of a module. BackPAN is where these deleted modules are backed up. It's more like a full CPAN mirror, only without the deletions. This module provides an index of BackPAN and some handy methods.



    my $backpan = BackPAN::Index->new(\%options);

Create a new object representing the BackPAN index.

It will, if necessary, download the BackPAN index and compile it into a database for efficient storage. Initial creation is slow, but it will be cached.

new() takes some options


Because it is rather large, BackPAN::Index caches a copy of the BackPAN index and builds a local database to speed access. This flag controls if the local index is updated.

If true, forces an update of the BACKPAN index.

If false, the index will never be updated even if the cache is expired. It will always create a new index if one does not exist.

By default the index is cached and checked for updates according to <$backpan-cache_ttl>>.


How many seconds before checking for an updated index.

Defaults to an hour.


If true, debug messages will be printed.

Defaults to false.


If true, only files in the authors directory will be considered as releases. If false any file in the index may be considered for a release.

Defaults to true.


Location of the cache directory.

Defaults to whatever App::Cache does.


URL to the BackPAN index.

Defaults to a sensible location.


    my $files = $backpan->files;

Returns a ResultSet representing all the files on BackPAN.


    my $files = $backpan->files_by($cpanid);
    my @files = $backpan->files_by($cpanid);

Returns all the files by a given $cpanid.

Returns either a list of BackPAN::Index::Files or a ResultSet.


    my $dists = $backpan->dists;

Returns a ResultSet representing all the distributions on BackPAN.


    my $dists = $backpan->dist($dist_name);

Returns a single BackPAN::Index::Dist object for $dist_name.


    my $dists = $backpan->dists_by($cpanid);
    my @dists = $backpan->dists_by($cpanid);

Returns the dists which contain at least one release by the given $cpanid.

Returns either a ResultSet or a list of the Dists.


    my $dists = $backpan->dists_changed_since($time);

Returns a ResultSet of distributions which have had releases at or after after $time.


    my $all_releases  = $backpan->releases();
    my $dist_releases = $backpan->releases($dist_name);

Returns a ResultSet representing all the releases on BackPAN. If a $dist_name is given it returns the releases of just one distribution.


    my $release = $backpan->release($dist_name, $version);

Returns a single BackPAN::Index::Release object for the given $dist_name and $version.


    my $releases = $backpan->releases_by($cpanid);
    my @releases = $backpan->releases_by($cpanid);

Returns all the releases of a single author.

Returns either a list of Releases or a ResultSet representing those releases.


    my $releases = $backpan->releases_since($time);

Returns a ResultSet of releases which were released at or after $time.


The real power of BackPAN::Index comes from DBIx::Class::ResultSet. Its very flexible and very powerful but not always obvious how to get it to do things. Here's some examples.

    # How many files are on BackPAN?
    my $count = $backpan->files->count;

    # How big is BackPAN?
    my $size = $backpan->files->get_column("size")->sum;

    # What are the names of all the distributions?
    my @names = $backpan->dists->get_column("name")->all;

    # What path contains this release?
    my $path = $backpan->release("Acme-Pony", 1.01)->path;

    # Get all the releases of Moose ordered by version
    my @releases = $backpan->dist("Moose")->releases
                                          ->search(undef, { order_by => "version" });


Michael G Schwern <>


Copyright 2009, Michael G Schwern


This module is free software; you can redistribute it or modify it under the same terms as Perl itself.


DBIx::Class::ResultSet, BackPAN::Index::File, BackPAN::Index::Release, BackPAN::Index::Dist

Repository: Bugs: