DH_INSTALLSYSTEMD(1)

📦
version 14.5ubuntu1 · 12 versions
, in ubuntu stonking

💖 DH_INSTALLSYSTEMD 💖

okay bestie, so this is a page from the Debhelper manual set, and it's literally the one that handles your systemd unit files. sit with me, we're gonna get through it together 🫶

✨ NAME ✨

dh_installsystemd — install systemd unit files 🎀

🌸 SYNOPSIS 🌸

dh_installsystemd [debhelper options] [--restart-after-upgrade]
[--no-stop-on-upgrade] [--no-enable] [--no-start] [--name=name]
[unit file ...]

🦋 DESCRIPTION 🦋

So dh_installsystemd is a debhelper program, and its whole job, its entire purpose, its main character era, is installing the systemd unit files that the package maintainer supplied. 💅

But wait, there's more (there's always more, iykyk). It also goes and finds the service files that a package installed, and it generates preinst, postinst, and prerm code blocks for enabling, disabling, starting, stopping, and restarting the matching systemd services whenever the package gets installed, updated, or removed. Those little snippets get added into your maintainer scripts by dh_installdeb(1). ✨

Now, deb-systemd-helper(1) is what actually does the enabling and disabling of systemd units. Which means — and this is the iconic part — the machine does not have to actually be running systemd at package installation time. Enabling happens on every machine, so you can switch from sysvinit to systemd and back again. no cap. 🔥

And here's how it decides what to touch: dh_installsystemd operates on all unit files installed by a package. If you only want blocks generated for specific unit files, just pass them as arguments, like "dh_installsystemd quota.service". And if you wanna exclude specific unit files from processing, that's what the -X common debhelper(1) option is for. 🙈

🎀 FILES 🎀

  • debian/package.mount, debian/package.path, debian/package@.path, debian/package.service, debian/package@.service, debian/package.socket, debian/package@.socket, debian/package.target, debian/package@.target, debian/package.timer, debian/package@.timer — if any of these exist, they get installed into usr/lib/systemd/system/ in the package build directory. 💖
  • debian/package.tmpfile — okay so this one is only used in compat 12 or earlier. In compat 13 and up, this file is handled by dh_installtmpfiles(1) instead, so it's not your girl anymore.

If it does exist, it's installed into usr/lib/tmpfiles.d/ in the package build directory. ✨

💅 OPTIONS 💅

  • -n, --no-scripts — do not modify postinst/postrm/prerm scripts.
heads up: this option was silently ignored before debhelper/13.24. so if you were relying on it in an older version... yeah, it just did nothing. 💀
  • --no-enable — disables the service(s) on purge, but does not enable them on install.
note that this does not affect whether the services are started. so please, please remember to also use --no-start if the service shouldn't be started. don't be out here catching strays from your own flags 🙈
  • --name=name — this option controls several things, she's got range.

It changes the name that dh_installsystemd uses when looking for maintainer-provided systemd unit files, as listed in the "FILES" section. Example time: dh_installsystemd --name foo will look for debian/package.foo.service instead of debian/package.service. Those unit files get installed as name.unit-extension — so in that example, it would be installed as foo.service. ⭐

AND, if no unit files are passed explicitly as command line arguments, dh_installsystemd will only act on unit files called name — rather than all the unit files found in the package. slay.

  • --restart-after-upgrade — do not stop the unit file until after the package upgrade has been completed. This is the default behaviour in compat 10. 👑

In earlier compat levels, the default was to stop the unit file in the prerm, and start it again in the postinst.

This can be useful for daemons that shouldn't have a possibly long downtime during upgrade. But — and this is a big but — you should make sure that the daemon won't get confused by the package being upgraded while it's running before you use this option. 🫶

  • --no-restart-after-upgrade — undoes a previous --restart-after-upgrade (or the default of compat 10). If no other options are given, this will cause the service to be stopped in the prerm script and started again in the postinst script. 💫
  • -r, --no-stop-on-upgrade, --no-restart-on-upgrade — do not stop the service on upgrade. This has the side-effect of not restarting the service as part of the upgrade.

If you want to restart the service with minimal downtime, please use --restart-after-upgrade (default in compat 10 or later). If you want the service restarted but also stopped during the upgrade, then please use --no-restart-after-upgrade — note the "after-upgrade". that word is doing so much heavy lifting bestie 😭

note that the --no-restart-on-upgrade alias is deprecated and will be removed in compat 14. This is to avoid confusion with the --no-restart-after-upgrade option. rip to a real one 💀
  • --no-start — do not start the unit file after upgrades, and after initial installation (that last bit is only relevant for services without a corresponding init script).
note that this option does not affect whether the services are enabled. please remember to also use --no-enable if the services should not be enabled. yes this is the mirror image of the --no-enable warning. they're a matching set, they're soulmates 💞
  • unit file ... — only process and generate maintscripts for the installed unit files with the (base)name unit file.
note: dh_installsystemd will still install unit files from debian/, but it will not generate any maintscripts for them unless they are explicitly listed in unit file ... so don't be surprised when the files show up anyway. that's just how she is. 🙈

🌈 NOTES 🌈

This command is not idempotent. dh_prep(1) should be called between invocations of this command (with the same arguments). Otherwise, it may cause multiple instances of the same text to be added to maintainer scripts. and like, duplicated maintainer script text is not the vibe, we don't want that ✋😭

💜 SEE ALSO 💜

debhelper(7), dh_installinit(1), deb-systemd-helper(1)

👑 AUTHORS 👑

pkg-systemd-maintainers@lists.alioth.debian.org

aaaand that's the whole page bestie, you ate that 🍓 go forth and install your unit files with confidence. this was 14.5ubuntu1, dated 2026-09-21 — mwah, kiss kiss, see you in the next manpage 💖✨🎀

📦 where this page comes from