Rebuild a corrupted local pacman database
Checked the wiki procedure against Pacman/Restore_local_database (raw wikitext, fetched 2026-09-06) and the pacman 7.1.0 source, and checked every Omarchy claim on this Omarchy 4 workstation (omarchy 4.0.2-1, pacman 7.1.0.r9.g54d9411-2). What held: the symptoms, the pacrecover script, the recovery-pacman flags, the ALPM_DB_VERSION note (the file exists here and contains 9, and /usr/bin/pacman-db-upgrade still ships and writes 9), and the tar prevention. What was wrong for Omarchy 4: the closing sudo pacman -Su is aborted by 00-omarchy-update-guard.hook, whose script /usr/bin/omarchy-update-pacman-guard treats the single argument -Su as both sync and sysupgrade (read on this machine), so the fix now ends with omarchy update or the OMARCHY_ALLOW_DIRECT_PACMAN=1 bypass, and the verify line no longer tells Omarchy users to run pacman -Syu. The record also ignored the better first recovery on Omarchy: omarchy update runs omarchy-snapshot create before every upgrade (read /usr/share/omarchy/bin/omarchy-update and omarchy-snapshot), the Snapper config is SUBVOLUME=/ with NUMBER_LIMIT=5 and TIMELINE_CREATE=no (/etc/snapper/configs/root and /usr/share/omarchy/default/snapper/root), and sudo snapper list here shows snapshots 1 and 2, with /.snapshots/2/snapshot/var/lib/pacman/local holding 1185 entries against 1188 live, while /.snapshots/2/snapshot/var/log is empty because /var/log is the separate @log subvolume (findmnt and btrfs subvolume list). The corrected fix adds that copy as the Omarchy first step and keeps the log-driven pass to close the gap, since the snapshot database predates the last update. Two defects that apply on plain Arch too: expac -l '\n' '%E' base without -S reads the local database being rebuilt (expac(1): -S searches the sync databases), and pacman -S --needed pacman-contrib expac against an empty database pulls the whole dependency tree into file conflicts, so the install now uses -dd --overwrite (pacman(8): -d twice skips all dependency checks). On Omarchy both tools are already installed from omarchy-base.packages. Confirmed from src/pacman/pacman.c at tag v7.1.0 that --dbonly sets NOSCRIPTLET and NOHOOKS, so no hook, including the guard, runs during the recovery-pacman steps. Added the single-package pacman -S --overwrite branch from the Pacman page and a yay build-directory argument for AUR packages (yay -Pg reports buildDir ~/.cache/yay here). Not exercised: no database was damaged or restored, no snapshot copy was made, and the recovery commands were not run. The snapshot copy and the -dd install are derived from the sources named, not from a live run.
This procedure uses --dbonly --overwrite '*' --nodeps, the most dangerous flag combination pacman has. Run it ONLY for database reconstruction, exactly as written. Get it wrong and you will need a full reinstall. Back up /var/lib/pacman and /var/log/pacman.log before starting. If /var/log/pacman.log is also gone, the log-driven method cannot be used. A database copied out of a Snapper snapshot is older than the files on disk. Stopping after the copy leaves pacman believing older versions are installed, and the next upgrade rewrites every package changed since the snapshot. omarchy-snapshot restore rolls back the whole root subvolume, not only the database, and discards every change made on / since that snapshot.
Symptom
pacman -Q prints nothing at all, or pacman -Syu claims the system is up to date on a machine that clearly is not, or pacman -S somepkg lists dependencies as "already satisfied" and refuses to install anything. May also show error: could not open file /var/lib/pacman/local/<pkg>/desc: No such file or directory.
Cause
/var/lib/pacman/local, pacman's record of what is installed, has been deleted, truncated, or corrupted (a full disk mid-transaction, a bad rm, a filesystem error, or restoring / from an incomplete backup). The files on disk are fine, but pacman just no longer knows about them.
Fix
pacman -Q reads only /var/lib/pacman/local. The package files on disk and /var/log/pacman.log are intact, and both recoveries below lean on the log, so check it is there first:
ls -l /var/log/pacman.log
**Omarchy 4: copy the database out of the last Snapper snapshot.** omarchy update takes a Snapper snapshot of the root subvolume before every upgrade (omarchy-snapshot create, retention NUMBER_LIMIT="5", timeline snapshots off), and /var/lib/pacman lives on that subvolume, so the newest snapshot holds a complete local database as it stood before the last update. /var/log is its own subvolume (@log) and is not in the snapshot, which is why the log survives whatever happened to the database.
sudo snapper list # pick the newest number, N
sudo mv /var/lib/pacman/local /var/lib/pacman/local.broken
sudo cp -a /.snapshots/N/snapshot/var/lib/pacman/local /var/lib/pacman/local
pacman -Q | wc -l # a full Omarchy install is over 1,000
That database is older than the files on disk: every package upgraded or installed since the snapshot is missing or recorded at the wrong version. Do not stop here. Continue with the log-driven pass below, which with --needed only touches those packages.
If more than the database is damaged, omarchy-snapshot restore rolls the whole root subvolume back to a snapshot, and the Limine boot menu lists the same snapshots under "Snapshots" with the kernel each one had. That returns /usr and the database to a matching state at the cost of everything changed on / since. /home is its own subvolume and is untouched. Run it as omarchy-snapshot restore, not under sudo: the script calls sudo itself.
**All systems: rebuild the database from the log.** paclog-pkglist (pacman-contrib) and expac are both in Omarchy's base package set, so on Omarchy they are already on disk and this install changes nothing. On plain Arch with an empty database a normal pacman -S would try to install their whole dependency tree and stop on file conflicts, so skip dependency checks and let it overwrite:
sudo pacman -S -dd --needed --overwrite '*' pacman-contrib expac
Create the recovery script. Any extra directory holding package files can be passed as an argument. yay's build directory (~/.cache/yay) matters for AUR packages, which are in no repository and can only come back from a cached file:
cat > /tmp/pacrecover <<'EOF'
#!/bin/bash -e
. /etc/makepkg.conf
PKGCACHE=$( (grep -m 1 '^CacheDir' /etc/pacman.conf || echo 'CacheDir = /var/cache/pacman/pkg') | sed 's/CacheDir = //')
pkgdirs=("$@" "$PKGDEST" "$PKGCACHE")
while read -r -a parampart; do
for pkgdir in "${pkgdirs[@]}"; do
for i in "$pkgdir"/"${parampart[0]}"-"${parampart[1]}"-*.pkg.tar.{xz,zst}; do
[ -f "${i}" ] && { echo "${i}" ; continue 3; }
done
done || echo "${parampart[0]}" 1>&2
done
EOF
chmod +x /tmp/pacrecover
cd /tmp
paclog-pkglist /var/log/pacman.log | ./pacrecover ~/.cache/yay/*/ >files.list 2>pkglist.orig
{ cat pkglist.orig; pacman -Slq; } | sort | uniq -d > pkglist
comm -23 <({ echo base; expac -S -l '\n' '%E' base; } | sort) pkglist.orig >> pkglist
expac -S reads the sync databases. Without -S expac reads the local database you are trying to rebuild and returns nothing for base.
Then reconstruct the database only. --dbonly also implies --noscriptlet and --nohooks, so no hook runs during these steps, including Omarchy's update guard:
recovery-pacman() { sudo pacman "$@" --log /dev/null --noscriptlet --dbonly --overwrite '*' --nodeps --needed; }
sudo pacman -Sy
recovery-pacman -U $(< /tmp/files.list)
recovery-pacman -S $(< /tmp/pkglist)
sudo pacman -D --asdeps $(pacman -Qq)
sudo pacman -D --asexplicit $(pacman -Qtq)
The two pacman -D lines recompute the install reason of every package. Skip them if you restored from a snapshot, which already carried the right reasons.
If you get failed to initialise alpm library, check for /var/lib/pacman/local/ALPM_DB_VERSION (pacman 7 writes 9 there). If it is missing, run sudo pacman-db-upgrade, then sudo pacman -Sy, and retry.
Finish with a full upgrade. On Omarchy the update guard aborts any pacman command line that carries both -S and -u, and -Su counts, so use the supported path or the one-transaction bypass:
omarchy update # Omarchy 4
sudo env OMARCHY_ALLOW_DIRECT_PACMAN=1 pacman -Su # Omarchy 4, one transaction only
sudo pacman -Su # plain Arch
**One damaged entry rather than the whole directory.** If the error names a single package (could not open file /var/lib/pacman/local/<pkg>-<ver>/desc, or file exists in filesystem for one package because its files list is empty or missing), the Pacman wiki's fix is to reinstall only that package with --overwrite:
sudo pacman -S --overwrite '*' <pkg>
**Prevention.** omarchy update already snapshots the root subvolume before each upgrade, so on Omarchy the last five updates are recoverable without any extra step. A tarball still covers the case where the snapshots are gone too:
sudo tar -cjf ~/pacman_database.tar.bz2 /var/lib/pacman/local
Verify
pacman -Q | wc -l returns a plausible package count, pacman -Qtdq lists only genuine orphans, and a full upgrade behaves normally: omarchy update on Omarchy 4, sudo pacman -Syu on plain Arch. pacman -Qk reports few or no missing files. If you copied the database from a snapshot, pacman -Qkk reports no size or checksum mismatches once the log-driven pass has run.
Sources
- https://wiki.archlinux.org/title/Pacman/Restore_local_database
- https://wiki.archlinux.org/title/Pacman/Tips_and_tricks
- https://man.archlinux.org/man/pacman.8
- https://wiki.archlinux.org/title/Pacman
- https://gitlab.archlinux.org/pacman/pacman/-/raw/v7.1.0/src/pacman/pacman.c
- https://gitlab.archlinux.org/pacman/pacman/-/raw/master/lib/libalpm/trans.c