Pacman Hooks: Declarative Automation for Arch Linux Updates

The problem: manual steps after every kernel update

Arch Linux’s rolling release model means frequent kernel upgrades. Each upgrade typically requires regenerating the initramfs and updating bootloader entries—steps that are easy to forget and tedious to run by hand. Pacman hooks solve this by letting you declare actions that run automatically during package transactions, keeping system state consistent without external cron jobs or wrapper scripts.

How hooks fit into the transaction

Hooks are declarative event handlers stored in two locations:

• /usr/share/libalpm/hooks – shipped with packages (read‑only for users)
• /etc/pacman.d/hooks – user‑defined hooks (safe from package overwrites)

Each hook file uses a simple INI‑like format with three required sections:

• Trigger – defines When (e.g., Install, Upgrade, Remove, PostTransaction) and Target package globs.
• Action – specifies Description, Exec (command run as root), and optional NeedsTargets.
• Optional – AbortOnFail to halt the transaction on error.

Because hooks execute inside the pacman transaction, their output appears in the pacman log, making the entire update reproducible and auditable.

Worked example: auto‑regenerate initramfs on kernel changes

Create a custom hook that runs mkinitcpio -P whenever the linux or linux-lts packages are installed or upgraded.

1. Ensure the hook directory exists:

   sudo mkdir -p /etc/pacman.d/hooks

2. Write the hook file /etc/pacman.d/hooks/90-mkinitcpio.hook:

   [Trigger]
   Type = Package
   Operation = Install
   Operation = Upgrade
   Target = linux
   Target = linux-lts
   
   [Action]
   Description = Regenerating initramfs for all kernels
   When = PostTransaction
   Exec = /usr/bin/mkinitcpio -P
   AbortOnFail

3. Verify syntax and permissions (hook files must be readable by root):

   sudo pacman -Sy --dry-run linux 2>&1 | grep -A2 -B2 '90-mkinitcpio'

   The dry‑run shows the hook would fire without making changes.
4. Run a real update to confirm:

   sudo pacman -S linux

   Check /var/log/pacman.log for lines like:

   [ALPM] running '90-mkinitcpio.hook'...
   [ALPM] Regenerating initramfs for all kernels
   [ALPM] completed '90-mkinitcpio.hook'

Trade‑offs and limitations

• Failure halts the transaction if AbortOnFail is set. A broken mkinitcpio run can leave the system without a valid initramfs, so test hooks on a non‑critical package first.
• Minimal environment – hooks run with a restricted PATH (typically /usr/bin:/bin), no interactive terminal, and working directory set to /. Always use absolute paths in Exec.
• Version sensitivity – the hook schema (supported When values, Target globbing) depends on the installed pacman/libalpm version. Older systems may lack PostTransaction or NeedsTargets.
• Ordering is not guaranteed across multiple hooks for the same trigger. If you need strict sequencing, combine steps into a single hook or a wrapper script.

Actionable next steps

1. List existing hooks to understand what’s already automated:

   find /usr/share/libalpm/hooks /etc/pacman.d/hooks -name '*.hook' -exec echo '=== {} ===' \; -exec cat {} \;

2. Create a benign test hook to verify the mechanism on your system:

   sudo tee /etc/pacman.d/hooks/99-test.hook >/dev/null <<'EOF'
   [Trigger]
   Type = Package
   Operation = Install
   Operation = Upgrade
   Target = *
   
   [Action]
   Description = Test hook fired
   When = PostTransaction
   Exec = /usr/bin/logger 'pacman hook test triggered'
   EOF

   Then run sudo pacman -S --needed base-devel and check journalctl -t pacman for the log entry.
3. Adapt the example hook for other repetitive tasks: updating fwupd metadata, rebuilding mandb, or syncing a local package repository.

Pacman hooks give you a transparent, version‑controlled way to codify the "after‑install" steps that keep an Arch system bootable and consistent. Start with the initramfs example, verify it in your logs, and then extend the pattern to any deterministic post‑transaction work.