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


ALPM - readonly access to pacman's libalpm.



This version of ALPM is compatible with pacman 4.


  ## We can start by setting options all by ourselves.
  use ALPM;
  my $alpm = ALPM->new('/', '/var/lib/db'); # root and dbpath
  ## Or use ALPM::Conf, a handy module for pacman.conf parsing.
  use ALPM::Conf qw(/etc/pacman.conf);
  ## ALPM::Conf loads an object into "our" package variable.
  our $alpm;
  ## Querying databases & packages
  my $localdb = $alpm->localdb;
  my $pkg = $localdb->find('perl') or die 'wtfbbq';
  printf "%s %s %s %d\n", $pkg->name, $pkg->version,
      $pkg->arch, $pkg->size;
  my $extradb = $alpm->register('extra') or die $alpm->strerror;
      or die $alpm->strerror;
  $extradb->update or die $alpm->strerror;
  my @perlpkgs = $extradb->search('perl');
  printf "%d perl packages found.\n", scalar @perlpkgs;
  ## libalpm's version comparison function. (a classy method)
  my $cmp = ALPM->vercmp('0.01', '0.02');
  if($cmp == -1){
        print "less than\n";
  }elsif($cmp == 0){
        print "equal\n";
  }elsif($cmp == 1){
        print "greater than\n";
  ## $found is undef or the package object for findme.
  my @syncdbs = $alpm->syncdbs;
  my $found = $alpm->find_dbs_satisfier('findme', @syncdbs);
  $found = $alpm->find_satisfier('findme', $extradb->pkgs);
  ## These are perl wrappers around localdb and syncdbs:
  ## Search all databases/repos (includes localdb).
  printf "%10s: %s %s\n", $_->db->get_name, $_->name,
        $_->version for $alpm->search('perl');
  ## Find a database by name of repository.
  my $coredb = $alpm->db('core');


Archlinux uses a package manager called pacman. Pacman internally uses the alpm library for handling its database of packages. This module creates a perlish object-oriented interface to the libalpm C library.

In the past this module implemented transactions as well, allowing you to modify the system/database. This is no longer implemented because I grew tired of rewriting this module every time the pacman API was changed.




The root directory for all deployed packages managed by libalpm.


The database directory where the local database and sync databases are kept.


An ALPM object which is used for all other method calls. This is referenced in the object method definitions below.


  $VERSTR = ALPM->version()

libalpm's internal version string, as returned by the alpm_version C function.


  @CAPS = ALPM->caps()

Corresponds to the alpm_capabilities C function. A list of strings, describing capabilities of libalpm. Any of the following capabilities may or may not be present:


Foreign language support.


If libcurl is installed then a downloader is embedded.


If gpgme is installed then package/database signatures are supported.


These methods can be used with ALPM objects created from the "new" method above. In the following methods, $OBJ represents an ALPM object.


  $ERRNO = $OBJ->errno()

The internal libalpm error number. If no error occurs this is zero.


  $ERRSTR = $OBJ->strerror()

The error string describing the last error that occurred. Note: the language of the error messages depends on the value of $ENV{LC_ALL}.


  $PKG | undef = $OBJ->find_satisfier($DEPSTR, @PKGS)

The dependency that libalpm should attempt to satisfy (e.g. 'foo', 'foo>2.0', etc.)


A list of ALPM::Package objects that are potential satisfiers.


If a package satisfies the dependency, it is returned.


Returned if no satisfier is found.


  $PKG | undef = $OBJ->find_dbs_satisfier($DEPSTR, @DBS)

The dependency that libalpm should attempt to satisfy (e.g. 'foo', 'foo>2.0', etc.)


A list of ALPM::DB objects whose packages will be searched for satisfiers


If a package satisfies the dependency, it is returned.


Returned if no satisfier is found.


  @CONFLICTS = $OBJ->check_conflicts(@PKGS)

A list of ALPM::Package objects which are checked for inter-conflicts.


A list of hashrefs describing any conflicts. See "Conflict".


  $PATH | undef = $OBJ->fetch_pkgurl($URL)

The url to a package file which will be downloaded to our default package cache location.


The path to our package file if the download succeeds.


If the download fails. Check "strerror".


  $PKG | undef = $PM->load_pkgfile($PATH, $FULL, $SIGLEVEL);

These parameters are kind of funky but they match the alpm_pkg_load function.


The path to a package file (i.e. pkg.tar.xz).


Full (1) or partial load (0). Trust me, don't install partial loads. That happened with clyde once.


Signature level hashref or the string "default". See "Signature Level".


On success, an ALPM::Package object.


On failure. Check "strerror".


  $DB = $OBJ->localdb()

An ALPM::DB::Local object.


  $DB | undef = $OBJ->register($NAME, $SIGLEVEL?)

Registers a remote synchronizable database.


The name to use for the database (e.g. core, extra, community.)

$SIGLEVEL (Optional)

The signature level to use for the database, including the database file and each package file downloaded from the database mirror. If none is specified, then the signature level is set to 'default' which is equivalent to the signature level set with the set_defsiglvl method.


On success, an ALPM::DB::Sync object.


On failure. Check "strerror".


  @DBS = $OBJ->syncdbs()

Retrieve a list of sync databases that have previously been registered.


A list of ALPM::DB::Sync objects.


  1 | undef = $OBJ->unregister_all()

Unregisters all sync databases. If you try to use previously registered ALPM::DB::Sync objects, they will probable cause a segfault...

Returns 1 on success or undef on error. Check "strerror" on error.


ALPM has a number of options corresponding to the alpm_option_get_... and alpm_option_set... C functions in the library. Options which take multiple values (hint: they have a plural name) accept multiple arguments in the corresponding methods. Similarly the same options return a list.

Read-write options

logfile - path to the pacman logfile
arch - the machine architecture to use
gpgdir - path to gpg stuff
cachedirs* - paths containing package caches
noupgrades* - a list of package names to not upgrade
noextracts* - a list of package names to not extract
assumeinstalled* - a list of dependencies to assume are satisfied. The setter methods take either a dependency hash or a string representing a dependency. The accessor returns a list of dependency hash references.
ignorepkgs* - a list of package names to ignore for upgrade
ignoregroups* - a list of groups to ignore for upgrade
usesyslog - if true, log to the system log as well
deltaratio - accepts a decimal from 0 to 1
checkspace - check for available diskspace
defsiglvl - the default signature level. See "Signature Level". This name was shortened from alpm_option_set_default_signature_level. You're welcome.

Read-only options

root - path to the installation root
dbpath - path to the database
lockfile - path to the lockfile
  * = the option is set with (and gets you) a list

Callback options

Callbacks can only be set to code references.

logcb - Generic logging

The log level and message are passed to the provided code ref as arguments.

1. level

This is one of the following strings: error, warning, debug, function, or unknown.

2. message

This is the message itself.


Several libalpm data types have been converted into hash references. The alternative is to turn them into full-blown objects, which seems pointless considering the only methods are data accessors.


Dependencies specify constraints on a set of packages. Only certain packages satisfy a dependency. These can be used in places other than dependencies, such as conflicts. Dependencies have the following keys:


The name of a package.


A version string, which can be empty.


A boolean operator used to compare package versions to our dependency version, must be either an empty string (which allows any version), =, >=, <=, >, <, or ? if an internal error occurred.


If the dependency is optional this key gives a description of the dependency. This key does not exist on a regular dependency.


Conflicts have the following keys:


An ALPM::Package object.


An ALPM::Package object.


A hashref that is identical to a dependency. See "Dependency".

Signature Level

Signature levels describe the level of security which is required for packages files and by databases files. Different degrees of signature checking can be used for either type of file. The signature checking is performed after the file is downloaded in order to verify the original packager. When gpg is not available an invalid argument error will be raised from libalpm if you try to set the siglevel.

A "siglvl" can either be the string "default" or a hash reference. A value of "default" can be used when registering a database to instruct libalpm to use the default siglevel that is set by set_defsiglvl. A siglvl hashref must contain a "pkg" key and a "db" key. Other keys are ignored.

Possible hash values include:


No signature verification is performed.


Signatures are optional. They are checked if they are available.


Signatures are required.

The string "trustall", preceded by a space, can be added to "optional" or "required" options to specify that signatures from anyone are to be trusted.

Here are some example siglevels:

  $alpm->set_defsiglvl({ 'pkg' => 'never', 'db' => 'never' });
  $alpm->set_defsiglvl({ 'pkg' => 'optional', 'db' => 'required trustall' });
  $alpm->set_defsiglvl({ 'pkg' => 'required', 'db' => 'optional' });


In previous version of this module, errors were thrown automatically. Since then, errors are no longer stored in a global variable (like UNIX's errno) but are instead stored inside of the libalpm handle structure. In order to preserve the old functionality I will have to either store a copy of the ALPM object inside every other object or use the internal C representation which I'm technically not supposed to know.

Whatever. I'm too lazy for either of those. What this means for you is you really really should check for errors yourself. If a method call returns undef you should follow it up with an "or die". Something like this:

  $db->force_update or die $alpm->strerror;

This is annoying but not unlike most other perl error checking. If you find yourself calling methods on an undefined value then an error most likely occurred.

But wait there's more! Errors are actually thrown when getting/setting options and an error condition occurs.



Justin Davis, <juster at cpan dot org>

Andrew Gregory <>


Copyright (C) 2015 by Justin Davis

Copyright (C) 2015 by Andrew Gregory <>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.