Ben Bullock


CPAN::Nearest - find the nearest module to a given name.


    use CPAN::Nearest 'search';
    my $mod = 'Lingua::Stop::Wars';
    my $pfile = "$ENV{HOME}/.cpan/sources/modules/02packages.details.txt.gz";
    print "Nearest to $mod in $pfile is '", search ($pfile, $mod), "'.\n";

produces output

    Nearest to Lingua::Stop::Wars in /home/ben/.cpan/sources/modules/02packages.details.txt.gz is 'Lingua::StopWords'.

(This example is included as in the distribution.)


This documents CPAN::Nearest version 0.13 corresponding to git commit 16243f456a77b2cd864ecc6243ce9eef74f89368 released on Fri Jan 13 10:24:59 2017 +0900.


This module provides a way of searching for CPAN modules whose name may be misspelt. For example, if a user accidentally types "Lingua::Stopwords" when looking for the module "Lingua::StopWords", the common cpan clients will not be able to function:

    cpan Lingua::Stopwords


    Warning: Cannot install Lingua::Stopwords, don't know what it is.
    Try the command

    i /Lingua::Stopwords/

    to find objects with matching identifiers.


    cpanm Lingua::Stopwords


    ! Finding Lingua::Stopwords on cpanmetadb failed.
    ! Finding Lingua::Stopwords on failed.
    ! Finding Lingua::Stopwords () on mirror failed.
    ! Couldn't find module or a distribution Lingua::Stopwords ()

CPAN::Nearest supplies a spelling-mistake tolerant search for the most similar name, intended for people making tools like cpan, cpanm, pm-uninstall, and anything else which needs to use the CPAN packages list. CPAN::Nearest was written to be fast enough for practical use.

CPAN::Nearest was inspired by the helpful "git" version control system, which provides suggestions for spelling mistakes.


    my $close_name = search ($file, $module_name);

Search the package detail file $file for a module named $module_name and return the closest name. E.g. if you search for "Harry::Potter",

    my $close_name = search ($file, 'Harry::Potter');

the value in $close_name, the closest CPAN module, is "Data::Lotter".

The file specified by the first argument, $file in the example, is usually found at ~/.cpan/sources/modules/02packages.details.txt.gz on a Unix-like system. This may be specified as the file name. This module can read either a compressed or uncompressed version. There is a speed increase of 10-20% when an uncompressed file is used.


Users of the cpan utility supplied with Perl may find the file listing the CPAN modules in ~/.cpan/sources/modules/02packages.details.txt.gz. Others can download the file from the directory /modules/ of any CPAN mirror.


The distribution includes a standalone program called "nearest-module" as shown in this blog entry. To use this program, edit the file nearest-module.c in the top level of the distribution to point to the name of the file 02packages.details.txt or 02packages.details.txt.gz on your system, and compile it with

    make -f makeitfile nearest-module

It is run with the name of a single module:

    ./nearest-module Lingo::Jingo::Mojo
    Closest to 'Lingo::Jingo::Mojo' is 'Lingua::JA::Moji'.

There is a -v option to view candidate modules:

    $ ./nearest-module -v Lingo::Jingo::Mojo
    Games::Bingo::Bot (9) is nearer than 10.
    Lingua::JA::Moji (7) is nearer than 9.
    Closest to 'Lingo::Jingo::Mojo' is 'Lingua::JA::Moji'.


Ben Bullock, <>


This package and associated files are copyright (C) 2012-2017 Ben Bullock.

You can use, copy, modify and redistribute this package and associated files under the Perl Artistic Licence or the GNU General Public Licence.