PKG-LUA-SCRIPT(5)

✨ PKG-LUA-SCRIPT(5) ✨

okay so bestie, welcome to the lua scripts page of the File Formats Manual 💅 this is literally the whole lore on the lua scripts that get run by pkg(8), and we're gonna get into all of it. no skipping, no skimming, we're doing this properly 🫶

---

🌸 DESCRIPTION 🌸

so pkg(8) runs scripts at specific phases of whatever process it's doing, right? and the phases are, in order of the vibes:

• pre-install — runs before the files get installed onto the system.
• post-install — runs after the files are installed onto the system.
• pre-deinstall — runs before the files get removed from the system.
• post-deinstall — runs after the files are removed from the system.

a package can hold multiple scripts per phase, and every single one of them gets run inside its own lua VM (yes, each one gets its own little main-character bubble 🫧).

now — the upgrade case is special and honestly kind of iconic. when it's an upgrade, the scripts run in this exact order:

1. new pre-install
2. old pre-deinstall
3. replace binaries
4. new post-install

and one thing that is not a vibe to forget: lua scripts are always run after shell scripts (of the same phase). always. periodt. 👑

---

🦋 API 🦋

all the regular lua APIs are available to you, EXCEPT for these changes. so listen up, because these are the rules 🔥

🌈 the modified ones

• io.open() — has been modified so it only opens files relatively to the rootdir if one was specified by the -r argument passed to pkg(8).
• os.remove() — has been modified so it only removes files relatively to the rootdir if one was specified by the -r argument passed to pkg(8).
• os.rename() — has been modified so it only renames files relatively to the rootdir if one was specified by the -r argument passed to pkg(8).
• os.execute() — has been disabled. like, gone. 💀
• os.exit() — has been disabled too. also gone. 💀

🎀 the variables (they come pre-defined for any lua script)

• pkg_name — the name of the package.
• pkg_prefix — the PREFIX defined within the package at build time.
• pkg_rootdir — represents the root directory where the package will be installed, as specified by the -r arguments passed to pkg(8).
• pkg_metalog — a String containing the path to a mtree(5) METALOG file where package file metadata (e.g., ownership, mode) should be recorded. this is typically used when installing packages as a non-root user. if no METALOG is configured, this variable is unset and is equal to nil.
• pkg_upgrade — a Boolean that informs the scripts whether or not it's running in the context of an upgrade.
• arg — okay this one's fun ✨ when the first line of a Lua script starts with -- args: followed by a space-separated list of tokens, those tokens get parsed and made available in the global arg table. this lets you pass arguments to Lua scripts — but it should not be used by regular scripts. it's used internally for deferred triggers. iykyk 🫶

💖 the added functions

• out pkg.prefixed_path(in) — prepends pkg_prefix to in if needed, and returns it as out.
• pkg.print_msg(msg) — sends messages to the user that will be shown at the end of the pkg(8) process.
• pkg.filecmp(file1, file2) — compares 2 files. returns 0 if the files are identical, 1 if the files are different, and >1 if an error occurred.
• pkg.metalog_copy(source, destination) — will create an entry in the "metalog" if one has been defined, which will clone the metadata from the source and use it for a new entry for the destination path.
• pkg.copy(source, destination) — copies a file preserving its attributes. returns -1 if an error occurred.
• st pkg.stat(file) — returns an object table st with the following fields: type, size, uid, gid.
• pkg.symlink(source, destination) — creates a symbolic link destination pointing at source.
• pkg.exec(arguments) — will execute the command arguments, expected in the following form: {command, arg1, arg2, arg3, ...}. the command inherits the parent's standard output and standard error.
• stdout, stderr, exitcode pkg.exec_capture(arguments) — will execute the command arguments, expected in the same form as pkg.exec(), capturing its standard output and standard error separately. returns three values: stdout (string containing the captured standard output), stderr (string containing the captured standard error), and exitcode (integer exit status of the command). if the command cannot be started, the first two return values are nil and exitcode contains the error number.
• res pkg.readdir(path) — will return an ipair with the list of elements contained in the directory; the special directory . and .. are filtered out.

---

🌟 SEE ALSO 🌟

the whole extended fam, go say hi 👋

pkg_create(3), pkg_printf(3), pkg_repo_create(3), pkg_repos(3), pkg-keywords(5), pkg-repository(5), pkg-script(5), pkg-triggers(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-triggers(8), pkg-unregister(8), pkg-update(8), pkg-updating(8), pkg-upgrade(8), pkg-version(8), pkg-which(8)

---

and that's the whole page bestie, you ate that 🍓 this lil masterpiece comes courtesy of Debian, dated April 14, 2026 — slay, go write some scripts 💜