Read and Write Debian deb822 Control Files

One missing leading space and half your package description turns into a broken field, which is why the deb822 format is worth learning properly. This guide takes about fifteen minutes, uses dpkg-dev 1.22.6ubuntu6.6 with the matching local deb822(5) manual page, and gives you a safe way to inspect the format on a running system.

You need a shell and ordinary read access to a Debian or Ubuntu system. None of the checks needs sudo.

deb822 is a data format, not a command. Debian uses it for package control data, source package metadata and upload files. The layout rules live in deb822(5). Which fields exist, and what they mean, depends on the file using the format, so take those from the relevant package manual.

1. Record the local tool version

Note the installed dpkg-dev version. It is read-only, and it explains small differences between machines:

$ dpkg-query -W -f='${Package} ${Version}\n' dpkg-dev
dpkg-dev 1.22.6ubuntu6.6

Your version may differ. The rules below come from the local manual page, not from an assumption that a newer development release is installed.

Checkpoint: you have the package version, and you know the rest of this guide only reads metadata.

2. Read a stanza as fields between blank lines

A deb822 file holds one or more stanzas. A stanza is a group of fields, and an empty line separates it from the next one. Each field is a name, a colon and a value. Field names are case-insensitive, though mixed case is the usual convention. Values are generally case-sensitive.

Package: example-tool
Version: 1.4.2-1
Architecture: amd64
Depends: libc6 (>= 2.38)

Package: example-tool-doc
Version: 1.4.2-1
Architecture: all
Depends: example-tool (= 1.4.2-1)

No stray spaces. Do not add spaces inside package names, architecture names, version numbers or multi-character version relationships.
One field, one time. A field may occur only once in a stanza.
Order matters. The ordering of stanzas is significant, so do not alphabetise or reorder them casually when a tool produced the file.

Whitespace immediately before or after a field value is ignored. A single space after the colon is conventional and makes hand-edited files easier to scan.

3. Pick the right multiline field shape

There are three useful shapes, and the file's specification decides which one a field accepts:

Simple. The whole value fits on one line.
Folded. It can continue on lines beginning with a space or tab, and the line breaks are not significant.
Multiline. It also uses indented continuation lines, but preserves their whitespace and newlines.

Maintainer: Example Maintainer <[email protected]>
Depends: libc6 (>= 2.38),
 libssl3 (>= 3.0)
Description: short package description
 A longer description starts on an indented line.
 .
 The dot represents a blank line in the field value.

The continuation lines above begin with one space. A line without that indentation starts a new field, so a missing leading space can turn part of a description or dependency list into malformed metadata.

The indented dot is the usual escaped blank line for multiline values.

Warning: never put a genuinely empty line inside a field. An empty line ends the stanza.

Empty field values are only permitted in source package control files such as debian/control. Other control files should not use an empty value as a placeholder.

4. Put package metadata in the right file

For a Debian source package, debian/control normally has one source package stanza followed by one stanza per binary package. It uses deb822 syntax, but the allowed fields and their meanings come from the source-control format. A small skeleton:

Source: example-tool
Section: utils
Priority: optional
Maintainer: Example Maintainer <[email protected]>
Standards-Version: 4.6.2
Build-Depends: debhelper-compat (>= 13)

Package: example-tool
Architecture: any
Depends: ${shlibs:Depends}, ${misc:Depends}
Description: small example command
 A longer description of what the command does.

This shows the format. It is not a complete package ready to build: the package version, source files and build rules are separate concerns. Do not copy field names from an unrelated control file without checking the manual for the file you are editing.

5. Inspect real installed data

The installed dpkg database holds deb822-style stanzas. Ask dpkg-query for chosen fields rather than editing the database directly:

$ dpkg-query -W -f='Package: ${Package}\nVersion: ${Version}\nArchitecture: ${Architecture}\nStatus: ${Status}\n\n' dpkg
dpkg: 1.22.6ubuntu6.6
Package: dpkg
Version: 1.22.6ubuntu6.6
Architecture: amd64
Status: install ok installed

The first line is the query command's package label. The stanza after it is assembled from fields held by dpkg, and your architecture and version may differ. It is handy for checking field spelling and values, but it is not a general-purpose deb822 linter.

You can also read repository metadata through APT's read-only cache:

$ apt-cache show dpkg | sed -n '1,12p'
Package: dpkg
Priority: required
Section: admin
Installed-Size: 6238
Maintainer: Ubuntu Developers <[email protected]>
Architecture: amd64
Version: 1.22.6ubuntu6.6

APT may print several stanzas, and repository metadata can change independently of the installed package. Treat the output as a current observation, not a file to edit.

6. Avoid the common parsing traps

Use UTF-8. Do not silently save control files in a legacy local encoding.
Comment only where allowed. Lines beginning with # are comments only in source package control files and deb-origin(5) files. It is not a universal comment syntax.
Start field names at column one. Indentation means continuation data, not a new field.
One blank line between stanzas. A line of only spaces or tabs may be accepted as a separator, but a genuinely empty line is the portable convention.
Never duplicate a field name in one stanza. For a list value, use the field's documented list syntax or continuation form.

Warning: before changing a package source, control file or repository configuration, make a backup and use the package tool's documented validation or build check. Such changes can affect dependency resolution and generated packages. The examples here make no persistent change, so there is nothing to undo.

Done means

Anatomy clear. You can identify stanzas, fields and continuation lines.
Separators known. A blank line ends a stanza and an indented line continues a field.
Shapes distinguished. You can tell simple, folded and multiline field values apart.
Real data checked. You read dpkg and APT metadata without elevated privileges.
Manual next. You will check the specific control-file manual before choosing fields or comments.