XBPS(7)

📦 version 0.60.6, in alpine 3.24, nixos 26.05, nixpkgs unstable

💅 XBPS(7) — like, the whole vibe of xbps, explained

okay so bestie, welcome to XBPS — that's the X Binary Package System — and it's the manual page for the entire package universe you're about to live in. This is XBPS(7), the miscellaneous info manual, and yes I'm gonna walk you through all of it. No skipping. 🫶

✨ NAME ✨

xbps — an introduction to the concepts, the lore, the whole thing.

🌸 DESCRIPTION 🌸

So. XBPS (the X Binary Package System, in case the acronym wasn't serving enough) is a binary package system that was designed and implemented from scratch. Not a fork, not a rehash — built fresh, main character energy from day one. 👑

Its goals? Be fast, easy to use, bug-free, featureful, and portable — as much as possible. That's the dream, and honestly? It ate.

The primary interface of XBPS is its cute little suite of tools, including:

And if you're a library girlie, there's also a C library called libxbps. Ngl, very demure, very mindful.

🎀 PACKAGES 🎀

An XBPS package is a compressed archive of the package's files and metadata. Simple as that.

Packages can also include scripts that run during installation and removal — during the “configuration” phase. And if you ever need to re-run those scripts? xbps-reconfigure -f. Slay.

Packages can be checked for issues with xbps-pkgdb(1). And if a package reports errors?? Bestie, reinstall it with xbps-install -f. Don't argue with the package database, it knows things.

Also iconic: packages can mark files as conf_files, which prevents them from being replaced upon package update if modified. Your configs are safe, periodt. 💖

🦋 PACKAGE EXPRESSIONS 🦋

Packages can be referred to in several ways. A package expression is a form to match a pattern, and currently xbps supports 3 ways to specify them:

  • by package name, i.e: foo
  • by exact package name and version, i.e: foo-1.0_1
  • by specifying a package name and version separated by any of the following version comparators:
<   less than
>   greater than
<=  less or equal than
>=  greater or equal than

Example: foo>=2.0

Heads up! The first repository matching the package expression wins. So order matters, iykyk. 👀

🔥 PACKAGE MODES 🔥

An installed package can have some specific modes of operation. Package modes can be changed with xbps-pkgdb(1). Currently these are the modes available:

hold

The package is on hold mode. Packages in this mode won't be updated unless it's explicitely declared to be updated. The only way to update packages in this mode is by using the -f, --force option. To list packages in this mode use xbps-query -H.

manual

The package is in manual mode of installation and won't be considered for removal when running xbps-remove -o. To list packages in this mode use xbps-query -m.

repolock

A package in repolock mode will only accept updates that are available in the same repository that was used for installing. To list packages in this mode use xbps-query --list-repolock-pkgs.

🌈 REPOSITORIES 🌈

An XBPS repository is a directory containing XBPS packages and an <arch>-repodata repository index file. And if the repository is remote (served via a web server), packages must be RSA-signed. That's not a suggestion, okay? 🔐

In XBPS configuration and command-line flags, repositories are specified by a complete url or an absolute path to the directory where the <arch>-repodata resides. To synchronize configured remote repositories locally, use xbps-install -S.

Repositories are created and managed with xbps-rindex(1). Yes, another tool. Collect them all. ⭐

👑 FILES 👑

  • /etc/xbps.d — Default configuration directory. See also xbps.d(5).
  • /usr/share/xbps.d — Default system configuration directory. See also xbps.d(5).
  • /var/db/xbps/.<pkgname>-files.plist — Package files metadata.
  • /var/db/xbps/pkgdb-0.38.plist — Default package database (0.38 format). Keeps track of installed packages and properties.
  • /var/cache/xbps — Default cache directory to store downloaded binary packages.

🧚 ENVIRONMENT 🧚

  • XBPS_ARCH — Overrides uname(2) machine result with this value.
  • XBPS_TARGET_ARCH — Sets the target architecture to this value.
  • XBPS_SYSLOG — Overrides the xbps.d(5) syslog=true|false configuration option.

💜 SEE ALSO 💜

xbps-alternatives(1), xbps-create(1), xbps-dgraph(1), xbps-fbulk(1), xbps-fetch(1), xbps-install(1), xbps-pkgdb(1), xbps-query(1), xbps-reconfigure(1), xbps-remove(1), xbps-rindex(1), xbps.d(5), https://github.com/void-linux/xbps, https://xbps-api-docs.voidlinux.org

Like, the whole friend group. Go say hi. 🫶

🍓 AUTHORS 🍓

  • Juan Romero Pardines <xtraeme@gmail.com>
  • Duncan Overbruck <mail@duncano.de>

Legends, fr fr. 💅

💀 BUGS 💀

Probably, but I try to make this not happen. Use it under your own responsibility and enjoy your life. 😭 (genuinely the most chill bug disclaimer ever written)

Report bugs at https://github.com/void-linux/xbps/issues

ok that's the whole page, you're officially an xbps girlie now 💖 go install something cute

<npink>mwah 💋 this was served up by the Debian build of this page, dated May 20, 2025, and yes it's the XBPS(7) manual — see you in the group chat bestie</npink> 🎀✨

(it's <pink> not npink — oops, but the sentiment stands 🫶)

📦 where this page comes from