DH_INSTALLDOCS(1)

📦
version 14.5ubuntu1 · 12 versions
, in ubuntu stonking

✨ NAME ✨

dh_installdocs — bestie, this is the one that installs your docs into the package build dirs 🎀

🌸 SYNOPSIS 🌸

dh_installdocs [debhelper options] [-A] [-Xitem] [file ...]

💖 DESCRIPTION 💖

okay so, dh_installdocs is a debhelper program, and its whole job is installing documentation into usr/share/doc/package inside your package build directories. she's the docs girlie 💅

If you're on compat 10 or earlier, dh_install(1) might genuinely be the better tool for handling upstream documentation — that's the case when upstream's own build system already installs all the documentation you want, correctly. But even then, dh_installdocs is still useful for the packaging-related docs, like the debian/copyright file. no cap.

Starting from debhelper compatibility level 11, dh_install will fall back to looking in debian/tmp for files if it doesn't find them in the current directory (or wherever you told it to look with --sourcedir). she has range ✨

And in compat 11 and later, dh_installdocs offers a bunch of the features that dh_install(1) also has. Plus — and this is the iconic part — dh_installdocs also supports the nodoc build profile to exclude documentation, regardless of compat level. it's giving "we contain multitudes" 🌈

🦋 FILES 🦋

  • debian/package.docs — a list of documentation files to be installed into the package.

Supports substitution variables in compat 13 and later, as documented in debhelper(7). slay.

  • debian/copyright — the copyright file gets installed into all packages, unless a more specific copyright file is available. she's the default queen 👑
  • debian/package.copyright
  • debian/package.README.Debian
  • debian/package.TODO

Each one of these gets installed automatically if it exists for a package. no config needed, she just shows up 💅

  • debian/README.Debian
  • debian/TODO

These get installed into the first binary package listed in debian/control.

Heads up bestie: README.debian files are also installed as README.Debian, and TODO files will be installed as TODO.Debian in non-native packages. the lowercase-to-capitalized glow-up is real 😭
  • debian/package.doc-base — installed as doc-base control files. Note that the doc-id will be determined from the Document: entry in the doc-base control file in question. iykyk.
  • debian/package.doc-base.* — if your package needs to register more than one document, you need multiple doc-base files, and you can name them like this.

Please be aware that the files are deduplicated in memory based on their doc-id. To work correctly, it requires dh_installdocs to be called no more than once during the package build. Calling dh_installdocs -ppackage in combination with using debian/package.doc-base.* files can lead to uninstallable packages. See <https://bugs.debian.org/980903> for details. not the vibe we're going for 💀

👑 OPTIONS 👑

  • -A, --all — install all files specified by command line parameters in ALL packages acted on. go big or go home.
  • -Xitem, --exclude=item — exclude files that contain item anywhere in their filename from being installed. Note that this includes doc-base files too. sorry doc-base girlies 🙈
  • --sourcedir=dir — look in the specified directory for files to be installed. This option requires compat 11 or later — it is silently ignored in compat 10 or earlier. the silent treatment fr fr 💀
Note that this is not the same as the --sourcedirectory option used by the dh_auto_* commands. You rarely need to use this option, since dh_installman automatically looks for files in debian/tmp in debhelper compatibility level 11 and above. close names, different girls 😭
  • --doc-main-package=main-package — set the main package for a documentation package. This is used to install the documentation of the documentation package in /usr/share/doc/main-package as recommended by the Debian policy manual 3.9.7 in §12.3.

In compat 11 (or later), this option is only useful if debhelper's auto-detection of the main package is wrong. The option can also be used to silence a warning from debhelper when the auto-detection fails but the default happens to be correct. she's not wrong, she's just loud 🫶

This option cannot be used when dh_installdocs is instructed to act on multiple packages. If you need this option, you will generally need to combine it with -p to ensure exactly one package is acted on. one at a time, bestie ✨

The X-Doc-Main-Package field can be used instead since debhelper/13.28. It has similar semantics but does not require command line options.

Please keep in mind that some documentation (the copyright file, README.Debian, etc.) will be unaffected by this option and the X-Doc-Main-Package field. they didn't get the memo 💅

  • --link-doc=package — make the documentation directory of all packages acted on be a symlink to the documentation directory of package. This has no effect when acting on package itself, or if the documentation directory to be created already exists when dh_installdocs is run. To comply with policy, package must be a binary package that comes from the same source package.

debhelper will try to avoid installing files into linked documentation directories that would cause conflicts with the linked package. The -A option will have no effect on packages with linked documentation directories, and copyright, changelog, README.Debian, and TODO files will not be installed. okay so she's on a diet when she's linked 😭

(An older method to accomplish the same thing, which is still supported, is to make the documentation directory of a package be a dangling symlink, before calling dh_installdocs.) vintage method, still cute 🌸

Please note that this option only applies to the documentation directory for the package itself. When the package ships documentation for another package (e.g. see --doc-main-package), it will not use a symlink for the documentation of the other package. boundaries 💅

CAVEAT 1: if a previous version of the package was built without this option and is now built with it (or vice-versa), it requires a "dir to symlink" (or "symlink to dir") migration. Since debhelper has no knowledge of previous versions, you have to enable this migration itself. that's on you, bestie 😭

This can be done by providing a debian/package.maintscript file and using dh_installdeb(1) to provide the relevant maintainer script snippets.

CAVEAT 2: the use of --link-doc should only be done when the packages have same "architecture" type. A link from an architecture independent package to an architecture dependent package (or vice versa) will not work. Since compat 10, debhelper will actively reject unsupported combinations. she said no 💀
  • file ... — install these files as documentation into the first package acted on. (Or in all packages if -A is specified.)

🎀 EXAMPLES 🎀

This is an example of a debian/package.docs file, look at her:

README
TODO
debian/notes-for-maintainers.txt
docs/manual.txt
docs/manual.pdf
docs/manual-html/

⭐ NOTES ⭐

Note that dh_installdocs will happily copy entire directory hierarchies if you ask it to — similar to cp -a, but excluding empty files. If it is asked to install a directory, it will install the complete contents of the directory. she does not do things halfway 🔥

🌈 SEE ALSO 🌈

This program is a part of debhelper. found family fr fr 🫶

💜 AUTHOR 💜

Joey Hess <joeyh@debian.org> — thank you for your service, king 👑

that's the whole page bestie!! this is debhelper version 14.5ubuntu1, dated 2026-09-21 — go install some docs and slay the build 💖✨🎀🦋🌸💅

📦 where this page comes from