PKG-TRIGGERS(5)

🎀 NAME 🎀

okay bestie, this is pkg-triggers(5) — the File Formats Manual page for the trigger file format. It’s giving “tiny automation notes that make big things happen” 💅

💖 DESCRIPTION 💖

Package triggers define commands to be executed when particular files are installed, modified, or removed by pkg(8). You can use triggers, for example, to update a database or index of files based on files installed by other packages. iconic behavior, no cap ✨

There are two kinds of triggers:

• Per-transaction — executed once at the end of the transaction, after all packages have been processed and all file changes committed to disk. Even if multiple packages match the same trigger, it is executed only once and receives the combined list of matched paths. one trigger, one slay, combined receipts 🫶
• Per-package — executed individually for each package as it is being installed or removed. Per-package triggers run at a specific phase of the operation (pre-install, post-install, pre-deinstall, or post-deinstall). Their failure is non-blocking: the package operation continues even if the trigger fails. so if it fumbles, the show still goes on 💀

Triggers are searched for in the list of directories configured by the PKG_TRIGGERS_DIR configuration option. By default, this includes /usr/share/pkg/triggers and <localbase>/share/pkg/triggers. Triggers are in UCL format and should have a .ucl extension. put that extension on it, bestie 🎀

🦋 Per-transaction triggers 🦋

Per-transaction trigger files are placed directly in a trigger directory.

The format is the following:

• description — an optional string providing a human-readable description of what the trigger does. nice for the girlies who read the docs
• path — an array of strings containing exact paths. Each time a package installs a file or directory whose name is equal to one of the strings, the trigger will be executed at the end of the transaction.
• path_glob — an array of strings containing shell-style glob patterns. Each time a package installs a file or directory whose name matches one of the patterns, the trigger will be executed at the end of the transaction.
• path_regexp — an array of strings containing regular expressions. Each time a package installs a file or directory whose name matches one of the regular expressions, the trigger will be executed at the end of the transaction.
• cleanup — an object which represents the script to execute in case the transaction results in removal of the trigger from the installation. The object requires the following fields:
  • type — the type of the script to be executed. The only supported type is Lua, indicated by the value lua (see pkg-lua-script(5)).
  • script — the script itself.
  • sandbox — a boolean controlling whether the script runs inside a capsicum(4) sandbox. Defaults to true. When disabled, the script has full system access including pkg.exec(). full system access is a big-girl privilege, okay? 🙈
• trigger — an object which represents the script to execute at the end of the transaction if a pattern has been matched. This object is required and has the following fields:
  • type — the type of the script to be executed. The only supported type is Lua, indicated by the value lua (see pkg-lua-script(5)).
  • script — the script itself. It will receive as arguments the list of paths that matched the patterns during the transaction.
  • sandbox — a boolean controlling whether the script runs inside a capsicum(4) sandbox. Defaults to true. When disabled, the script has full system access including pkg.exec().

🧚 Per-package triggers 🧚

Per-package trigger files are placed in a subdirectory of a trigger directory named after the phase at which they should execute:

• pre_install/ — before the package files are extracted.
• post_install/ — after the package files have been extracted and post-install scripts have run.
• pre_deinstall/ — before the package files are removed.
• post_deinstall/ — after the package files have been removed and post-deinstall scripts have run.

For example, a trigger that should run after each package installation would be placed in:

<localbase>/share/pkg/triggers/post_install/mytrigger.ucl

The file format is the same as for per-transaction triggers. The path, path_glob, and path_regexp fields are used to match the files and directories of the individual package. The trigger object contains the script to execute. same format, different phase, still slaying ✨

Per-package triggers are reloaded from disk before processing each package, so a trigger installed by an earlier package in the same transaction will be active for subsequent packages. fresh reload, fresh vibes 🦋

In addition to the arg table containing matched paths, per-package trigger scripts have access to the following Lua global variables:

• pkg_name — the name of the package being processed.
• pkg_version — the version of the package being processed.
• pkg_upgrade — a boolean set to true if the operation is part of an upgrade, or false for a fresh installation or a standalone removal. upgrade? true. fresh install or standalone removal? false. periodt. 👑

👑 SEE ALSO 👑

go read these next, bestie — every single one is listed in the vibe check: pkg_create(3), pkg_printf(3), pkg_repo_create(3), pkg_repos(3), pkg-keywords(5), pkg-lua-script(5), pkg-repository(5), pkg-script(5), pkg.conf(5), pkg(8), pkg-add(8), pkg-alias(8), pkg-annotate(8), pkg-audit(8), pkg-autoremove(8), pkg-check(8), pkg-clean(8), pkg-config(8), pkg-create(8), pkg-delete(8), pkg-fetch(8), pkg-help(8), pkg-info(8), pkg-install(8), pkg-key(8), pkg-lock(8), pkg-plugins(8), pkg-query(8), pkg-register(8), pkg-repo(8), pkg-repositories(8), pkg-rquery(8), pkg-search(8), pkg-set(8), pkg-shell(8), pkg-shlib(8), pkg-ssh(8), pkg-stats(8), pkg-unregister(8), pkg-update(8), pkg-updating(8), pkg-upgrade(8), pkg-version(8), pkg-which(8).

---

That’s the whole page, bestie 🫶 — this one’s sourced from Debian, dated March 4, 2026, and it’s PKG-TRIGGERS(5) signing off. 💖