Weekend Project: xbps-command-not-found

18 jan 2026

This weekend, I wrote a small script to suggest installation of XBPS packages in interactive shell sessions when a command isn't found.

If you've ever used Debian or Ubuntu, you've possibly seen something similar from your shell. There are also similar programs for other distros, like Gentoo, and semi-distro-agnostic like pay-respects.

However, none of these existing implementations really had the right feel to me. There's no real reason this needs to be written in Rust or Python, or use a whole database (Debian please!). All we need is a little shell... and it can be POSIX to boot.

Since a little under a year ago, XBPS packages have been given virtual package names in the format cmd:<name> for binaries (and alternatives) they provide. This means you can search the repositories with a command like:

$ xbps-query -Rp provides -s cmd:awk
busybox-1.34.1_12: cmd:awk-0_1 (https://repo-fastly.voidlinux.org/current)
busybox-core-1.34.1_12: cmd:awk-0_1 (https://repo-fastly.voidlinux.org/current)
busybox-huge-1.34.1_12: cmd:awk-0_1 (https://repo-fastly.voidlinux.org/current)
gawk-5.3.2_1: cmd:awk-0_1 (https://repo-fastly.voidlinux.org/current)
mawk-1.3.4.20250131_2: cmd:awk-0_1 (https://repo-fastly.voidlinux.org/current)
nawk-20251225_1: cmd:awk-0_1 (https://repo-fastly.voidlinux.org/current)

and it will show every package that could provide the command awk!

You can also use this when installing packages¹:

# xbps-install cmd:zola

Name Action    Version           New version            Download size
zola install   -                 0.22.0_1               -

I've leveraged this behaviour for xbps-command-not-found. In bash, zsh, fish, and nushell, it is possible to run something when the user tries to run a non-existent command. In interactive shells, xbps-command-not-found searches the XBPS repositories for cmd: provides based on the command attempted. If it finds potential providers for the command, it prints a message like this:

$ vim
The command "vim" was not found, but is available from the following packages:
    - gvim
    - neovim
    - vim
    - vim-x11
and can be installed with xbps-install.

If you'd like to give it a try, you can install xbps-command-not-found now from XBPS on Void Linux. To configure it for your shell, read the manual page.

The source code is available here.