Track Debian Releases from Scripts with debian-distro-info

You will finish with commands that identify Debian's stable, testing and development releases without hard-coding today's codename into a script. The examples use debian-distro-info from package distro-info 1.7build1, installed on this machine, with the local debian-distro-info(1) manual as the primary reference.

Allow about ten minutes. You need a shell and the distro-info package. Everything here is read-only and runs as your normal user. No sudo, service restart or repository change is needed.

1. Check the installed command

Confirm which executable will run and which package supplied it:

$ command -v debian-distro-info
/usr/bin/debian-distro-info
$ dpkg-query -W -f='${Package} ${Version}\n' distro-info
distro-info 1.7build1

Then read the installed help:

$ debian-distro-info --help
Usage: debian-distro-info [options]

The manual page installed here is older than the command. Its core options are the same, but this command also advertises --oldstable, --lts, --elts and the eol-lts and eol-elts milestones. When writing a script for this package version, check --help on the target system before using those newer options.

2. Ask for the current release role

Use one selector at a time when you need a particular moving release:

$ debian-distro-info --stable
trixie
$ debian-distro-info --testing
forky
$ debian-distro-info --oldstable
bookworm
$ debian-distro-info --devel
sid

These selectors return the codename by default. The result changes as Debian promotes releases, so capture it in a variable rather than treating trixie or forky as permanent facts:

$ stable=$(debian-distro-info --stable)
$ printf 'stable codename: %s\n' "$stable"
stable codename: trixie

Checkpoint: if a script needs a codename, it should now use the command result. If it needs a release number or display name, choose the output format explicitly in the next step.

3. Choose the output format

--codename is the default. Add --release for the numeric release or --fullname for Debian's display name:

$ debian-distro-info --stable --codename
trixie
$ debian-distro-info --stable --release
13
$ debian-distro-info --stable --fullname
Debian 13 "Trixie"

Use the short forms only when you control the surrounding command. Long options are easier to audit in deployment scripts:

$ debian-distro-info --stable --release
13
$ debian-distro-info --stable --fullname
Debian 13 "Trixie"

Do not parse the full name to recover the number. Ask for --release directly. That keeps a script independent of punctuation and capitalisation in human-readable output.

4. Inspect every known or supported series

Use --all when you need the complete data set, including old releases and development series. Add an output selector if a list of release numbers is more useful than codenames:

$ debian-distro-info --all --release
1.1
1.2
...
13
14
sid
experimental

The ellipsis above is explanatory, not literal command output. For a shorter operational list, use --supported. On this installation it includes stable, testing and development entries:

$ debian-distro-info --supported
trixie
forky
sid
experimental

--unsupported lists unsupported stable releases. The command does not upgrade, remove or enable anything; it only reads the distro-info data shipped with the package.

5. Reproduce the answer for a historical date

Release roles move over time. Pass an ISO date with --date=YYYY-MM-DD when testing an old deployment decision or a dated build:

$ debian-distro-info --date=2024-01-01 --stable --codename
bookworm
$ debian-distro-info --date=2024-01-01 --stable --release
12

Without --date, the command uses today. The manual also documents SOURCE_DATE_EPOCH as the default epoch when it is set; verify the behaviour on the target package if reproducible builds depend on it:

$ SOURCE_DATE_EPOCH=1704067200 debian-distro-info --stable --release
12

Invalid dates fail instead of silently choosing a release:

$ debian-distro-info --date=not-a-date --stable
debian-distro-info: invalid date `not-a-date'

6. Convert a codename to its current alias

--alias=DIST answers a different question: which role does a given codename have now?

$ debian-distro-info --alias=bookworm
oldstable
$ debian-distro-info --alias=trixie
stable
$ debian-distro-info --alias=forky
testing
$ debian-distro-info --alias=sid
unstable

Only lower-case ASCII codenames are accepted. An otherwise valid but unknown lower-case codename is returned unchanged:

$ debian-distro-info --alias=notarelease
notarelease
$ debian-distro-info --alias=Bad-Name
debian-distro-info: invalid distribution codename `Bad-Name'

That unchanged result is not proof that the name is a real Debian series. If validity matters, compare it with a list from --all or handle an unknown name as an application-level error.

7. Add release dates or end-of-life estimates

The --days option appends or returns the number of days until a milestone. The local manual documents created, release and eol; this installed command additionally accepts eol-lts and eol-elts:

$ debian-distro-info --days=release --stable
-410
$ debian-distro-info --days=eol --stable
686

A negative number means the milestone is in the past relative to the calculation date. With a list option, the normal value and a day count are combined, so use a single selector when a machine-readable scalar is required. Dates and support data can change as package data is updated; do not treat the number as a maintenance guarantee.

8. Keep scripts predictable

Prefer explicit selectors and output formats, quote shell variables, and check the exit status before using a result:

$ series=$(debian-distro-info --stable --codename) || exit 1
$ release=$(debian-distro-info --stable --release) || exit 1
$ printf 'Debian %s (%s)\n' "$release" "$series"
Debian 13 (trixie)

Do not use this tool as an upgrade mechanism and do not infer that a release is safe to deploy merely because it is labelled stable. It reports distro-info's data. Package compatibility, security support and your own change controls remain separate checks. There is no recovery step because every example only queries local metadata.