<!--
SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me>

SPDX-License-Identifier: BSD-3-Clause
-->

# prometheus-pacman-exporter

A Prometheus metrics exporter for [pacman](https://archlinux.org/pacman/),
designed to be run via a systemd timer and consumed by the [node exporter
textfile
collector](https://github.com/prometheus/node_exporter#textfile-collector).

## Requirements

- Python 3.12+
- pacman
- checkupdates (optional)
- An AUR helper or other update command (optional)

## Installation

```bash
pip install prometheus-pacman-exporter
```

## Usage

```
Usage: prometheus-pacman-exporter [OPTIONS]

  Collect pacman package metrics and export them for Prometheus.

  Queries pacman for installed package statistics and available updates, then
  writes them to a .prom file for consumption by the Prometheus node exporter
  textfile collector.

  By default, updateable packages are determined using pacman --query
  --upgrades. Use --use-checkupdates to query updates with checkupdates
  instead. AUR update metrics can optionally be collected by providing --aur
  together with --aur-command.

Options:
  --textfile-collector-dir DIRECTORY
                                  Directory where the Prometheus collector
                                  textfile will be written.
                                  [default: /var/lib/prometheus/node-exporter]
  --use-checkupdates              Use checkupdates instead of pacman to check for
                                  available package updates.
  --aur                           Include AUR updates.
  --aur-command TEXT              Command used to check for AUR updates.
  --color [auto|always|never]     Colorize the output. A bare --color is the
                                  same as --color=always.
                                  [default: auto]
  --no-color                      Disable colorization (alias of
                                  --color=never).
  -q, --quiet                     Suppress all non-error output.
  -v, --verbose                   Enable verbose output.
  --version                       Show version information and exit.
  -h, --help, -?                  Show this message and exit.
```

### Checking for updates

By default, available repository updates are determined using:

```bash
pacman --query --upgrades
```

This only reports updates already known to the local package database.

Use `--use-checkupdates` to instead use
[`checkupdates`](https://man.archlinux.org/man/checkupdates.8), which checks
for available updates without modifying the system's package database:

```bash
prometheus-pacman-exporter --use-checkupdates
```

### AUR updates

AUR updates can be included with `--aur`. An update command must also be
provided with `--aur-command`:

```bash
prometheus-pacman-exporter \
    --aur \
    --aur-command "paru --query --upgrades --aur"
```

The AUR command may use any AUR helper or custom program, provided its standard
output contains **exactly one available package update per line**. The exporter
counts the number of output lines; it does not interpret the contents of those
lines.

For example, output such as:

```text
package-one 1.2.3-1 -> 1.2.4-1
package-two 4.5.6-1 -> 4.6.0-1
```

is interpreted as two available AUR updates.

Diagnostic or informational messages from the command should therefore be
written to standard error rather than standard output.

The value of `--aur-command` is split into command-line arguments and executed
directly. It is not executed through a shell, so shell features such as pipes,
redirections, variable expansion, and command substitution are not available.

## Metrics

| Metric                           | Description                                        |
| -------------------------------- | -------------------------------------------------- |
| `pacman_installed_packages`      | Total number of installed packages                 |
| `pacman_explicit_packages`       | Number of explicitly installed packages            |
| `pacman_depends_packages`        | Number of packages installed as dependencies       |
| `pacman_unrequired_packages`     | Number of packages not required by another package |
| `pacman_foreign_packages`        | Number of packages not present in sync databases   |
| `pacman_native_packages`         | Number of packages present in sync databases       |
| `pacman_orphan_packages`         | Number of orphaned dependency packages             |
| `pacman_updateable_packages`     | Number of available repository package updates     |
| `pacman_aur_updateable_packages` | Number of available AUR package updates            |

The AUR update metric is only collected when `--aur` is enabled.

## License

BSD-3-Clause. See [LICENSE](LICENSES/BSD-3-Clause.txt) for details.