Debian Maintainer Scripts: preinst, postinst, prerm, postrm

Debian packages rely on maintainer scripts to perform dynamic actions that simple file extraction cannot handle. These executable shell scripts—specifically preinst, postinst, prerm, and postrm—run at distinct phases of a package's lifecycle, including installation, upgrade, removal, and purging. This guide explains the purpose, execution timing, and common use cases for each of these four critical control scripts used by Debian's package manager (dpkg).

What Are Maintainer Scripts?

Maintainer scripts are executable scripts packaged inside the control archive (control.tar.xz or control.tar.gz) of a .deb package. They are typically written as POSIX-compliant shell scripts (/bin/sh), though they can technically be written in any scripting language installed on the target system.

When you install or remove software using tools like apt or dpkg, the package manager invokes these scripts with specific arguments to prepare the system, configure software, stop or start services, and clean up residual files.

1. preinst (Pre-Installation Script)

The preinst script is executed before the package's files are unpacked from the archive onto the filesystem.

Primary Purpose

To prepare the system for the upcoming installation or upgrade, ensuring that the new files can be placed cleanly without conflicts or corruption.

Common Use Cases:

Stopping an existing version of a service before replacing its binary files.
Checking system dependencies or hardware compatibility that cannot be expressed in standard package metadata.
Backing up or migrating older configuration files before new ones are written.

2. postinst (Post-Installation Script)

The postinst script is executed after the package files have been unpacked onto the filesystem.

Primary Purpose

To configure the package, initialize data, register system components, and start services so the software becomes fully functional.

Common Use Cases:

Running configuration dialogs using debconf to ask the user for setup choices.
Creating required system users and groups (adduser, addgroup).
Registering icons, desktop files, or man pages with system databases (update-desktop-database, mandb).
Initializing databases or setting strict file permissions.
Starting or enabling systemd services (systemctl enable --now).

3. prerm (Pre-Removal Script)

The prerm script is executed before any of the package's files are deleted from the system during an uninstallation or upgrade.

Primary Purpose

To gracefully shut down active components and deactivate features before the underlying executables and libraries are removed.

Common Use Cases:

Stopping running daemons and services associated with the package.
Unregistering system alternatives (update-alternatives --remove).
De-registering system integrations, such as menu entries or browser plugins.

4. postrm (Post-Removal Script)

The postrm script is executed after the package files have been deleted from the filesystem. It also runs during the final purge phase.

Primary Purpose

To clean up residual state data, modify system integrations, or completely erase configuration files when a package is purged.

Common Use Cases:

Updating system caches after binary removal (e.g., ldconfig, update-mime-database).
Removing dynamically generated cache files or logs that were not part of the original .deb payload.
Deleting configuration files and databases when invoked with the purge argument.
Removing system users or groups that were dedicated solely to that package (when purged).

Summary of Execution Flow

Installation: preinst (install) \(\rightarrow\) Unpack files \(\rightarrow\) postinst (configure)
Upgrade: Old prerm (upgrade) \(\rightarrow\) New preinst (upgrade) \(\rightarrow\) Unpack files \(\rightarrow\) Old postrm (upgrade) \(\rightarrow\) New postinst (configure)
Removal (remove): prerm (remove) \(\rightarrow\) Delete package files \(\rightarrow\) postrm (remove)
Purge (purge): Runs postrm (purge) to delete lingering configurations and data.