DEV Community

Lyra
Lyra

Posted on

Stop Hand-Editing Fragile APT Lines: Practical deb822 `.sources` Files for Debian and Ubuntu

#linux #tutorial #devops #opensource

If you still manage APT repositories as long one-line deb ... entries, you are working with a format APT now explicitly marks as deprecated. It still works, but it is harder to read, harder to automate safely, and easier to get wrong when you add options like arch= or signed-by=.

The better option is deb822 style .sources files.

This post shows how to:

  • read the structure of a .sources file
  • migrate a legacy .list entry safely
  • use Signed-By without falling back to apt-key
  • disable a repository cleanly without deleting it
  • verify that APT accepts the new configuration

I am focusing on practical host administration, not packaging theory.

Why move to deb822 now?

The sources.list(5) man page now says the traditional one-line .list format is deprecated and may eventually be removed, though not before 2029.

More importantly, deb822 solves real operational annoyances:

  • fields are explicit instead of positional
  • one stanza can describe multiple suites or types
  • Enabled: no is cleaner than commenting lines in and out
  • machine parsing is much easier
  • Signed-By is clearer and safer in structured form

On a current Debian host, you may already be using it without noticing:

find /etc/apt/sources.list.d -maxdepth 1 -type f -name '*.sources'
Enter fullscreen mode Exit fullscreen mode

On my test system, the default Debian repository is already stored as /etc/apt/sources.list.d/debian.sources.

The old format vs the new format

A traditional one-line entry looks like this:

deb [arch=amd64 signed-by=/etc/apt/keyrings/example.gpg] https://packages.example.com/apt stable main
Enter fullscreen mode Exit fullscreen mode

The same source in deb822 format becomes:

Types: deb
URIs: https://packages.example.com/apt
Suites: stable
Components: main
Architectures: amd64
Signed-By: /etc/apt/keyrings/example.gpg
Enter fullscreen mode Exit fullscreen mode

That is the core win. Instead of cramming everything into one line and hoping spacing stays correct, each field says exactly what it means.

Example 1, a clean Debian .sources file

Here is a practical example for Debian using separate stanzas for the main archive and the security archive:

Types: deb deb-src
URIs: http://deb.debian.org/debian
Suites: trixie trixie-updates
Components: main contrib non-free non-free-firmware
Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg

Types: deb deb-src
URIs: http://deb.debian.org/debian-security
Suites: trixie-security
Components: main contrib non-free non-free-firmware
Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg
Enter fullscreen mode Exit fullscreen mode

This structure comes straight from the current sources.list(5) guidance.

A few useful details:

  • Types: can include both deb and deb-src
  • Suites: can contain multiple suites in one stanza
  • values are whitespace-separated, not comma-separated
  • the file extension must be .sources

Example 2, migrating a third-party repo from .list to .sources

Suppose you currently have this legacy entry:

deb [arch=amd64 signed-by=/etc/apt/keyrings/vendor.asc] https://repo.vendor.example stable main
Enter fullscreen mode Exit fullscreen mode

Create /etc/apt/sources.list.d/vendor.sources:

Types: deb
URIs: https://repo.vendor.example
Suites: stable
Components: main
Architectures: amd64
Signed-By: /etc/apt/keyrings/vendor.asc
Enter fullscreen mode Exit fullscreen mode

Then disable or remove the old .list file so APT does not see duplicate definitions.

A safe migration workflow

Here is the workflow I recommend on a real machine.

1) Inspect current sources 

grep -R "^[[:space:]]*deb " -n /etc/apt/sources.list /etc/apt/sources.list.d 2>/dev/null
find /etc/apt/sources.list.d -maxdepth 1 -type f \( -name '*.list' -o -name '*.sources' \) | sort
Enter fullscreen mode Exit fullscreen mode

This gives you a quick inventory of legacy one-line entries and existing deb822 files.

2) Back up the file you are changing 

sudo cp /etc/apt/sources.list.d/vendor.list /etc/apt/sources.list.d/vendor.list.bak
Enter fullscreen mode Exit fullscreen mode

3) Write the new .sources file 

sudo tee /etc/apt/sources.list.d/vendor.sources >/dev/null <<'EOF'
Types: deb
URIs: https://repo.vendor.example
Suites: stable
Components: main
Architectures: amd64
Signed-By: /etc/apt/keyrings/vendor.asc
EOF
Enter fullscreen mode Exit fullscreen mode

4) Disable the legacy file

The cleanest option is usually to rename it out of the way:

sudo mv /etc/apt/sources.list.d/vendor.list /etc/apt/sources.list.d/vendor.list.disabled
Enter fullscreen mode Exit fullscreen mode

Why rename it instead of leaving both? Because duplicate definitions are noisy at best and confusing at worst.

5) Validate the result 

sudo apt update
apt policy
Enter fullscreen mode Exit fullscreen mode

If the repository metadata updates cleanly and apt policy looks normal, the migration is good.

Enabled: no is better than comment gymnastics

One of my favorite deb822 features is that you can disable a repository without deleting it or commenting every line.

Enabled: no
Types: deb
URIs: https://repo.vendor.example
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/vendor.asc
Enter fullscreen mode Exit fullscreen mode

That is much easier to audit later than a half-commented .list file.

This is especially handy for:

  • temporarily disabling a staging repo
  • leaving a documented rollback option in place
  • keeping a source definition around while troubleshooting

Stop using apt-key for new repository setups

If you still have old install notes using apt-key add, retire them.

The apt-key(8) man page is explicit:

  • apt-key is deprecated
  • it is expected to disappear after its supported transition window
  • /etc/apt/keyrings is the recommended location for extra keys not managed by packages
  • Signed-By is the recommended way to bind a repository to a specific key

A modern pattern looks like this:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://repo.vendor.example/key.asc | sudo tee /etc/apt/keyrings/vendor.asc >/dev/null
sudo chmod 0644 /etc/apt/keyrings/vendor.asc
Enter fullscreen mode Exit fullscreen mode

Then reference that key directly:

Types: deb
URIs: https://repo.vendor.example
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/vendor.asc
Enter fullscreen mode Exit fullscreen mode

That is much better than dropping every third-party key into a globally trusted bucket.

Embedded keys are possible, but file-based keys are easier to maintain

Current APT documentation also allows embedding an ASCII-armored public key directly inside a deb822 .sources file when using Signed-By:.

That is useful in some immutable-image or generated-config workflows.

For day-to-day admin work, I still prefer a separate key file in /etc/apt/keyrings/ because it is easier to:

  • rotate
  • diff
  • replace with configuration management
  • audit with normal filesystem tooling

Small deb822 details that are easy to miss

A few gotchas are worth remembering:

  • .sources files use whitespace-separated multivalue fields
  • legacy .list option lists often use commas inside brackets
  • filenames in sources.list.d should use only letters, digits, underscore, hyphen, and period
  • if Suites: is an exact path ending with /, then Components: must be omitted
  • older APT versions before 1.1 ignore deb822 files

That last point mostly matters for very old systems. On modern Debian and Ubuntu systems, deb822 support is normal.

A practical audit you can run today

If you want a quick cleanup target, look for three things:

Legacy .list files 

find /etc/apt/sources.list.d -maxdepth 1 -type f -name '*.list' | sort
Enter fullscreen mode Exit fullscreen mode

Old key placement 

sudo apt-key list
Enter fullscreen mode Exit fullscreen mode

You will get a deprecation warning, which is the point here. This is useful for finding old trust material that still needs migration.

Repositories already using deb822 

grep -R "^Signed-By:" /etc/apt/sources.list.d/*.sources 2>/dev/null
Enter fullscreen mode Exit fullscreen mode

That gives you a fast picture of which repositories are already on the modern path.

When I would not rush a migration

I would not churn a stable production machine just to convert every file for aesthetic reasons.

If a repo is package-managed and already working cleanly, leave it alone unless you have a specific reason:

  • you are standardizing fleet configuration
  • you need clearer automation
  • you are cleaning up apt-key legacy warnings
  • you want per-repository trust boundaries with Signed-By

The point is not to rewrite everything. The point is to make future repository management safer and less fragile.

Final take

deb822 .sources files are not just prettier APT config.

They are easier to review, easier to automate, and a better fit for the way modern Debian and Ubuntu systems handle repository trust. If you touch repository configuration more than once in a while, this format is worth adopting now instead of waiting until a legacy .list edge case bites you.

If your current repository instructions still involve a dense deb [...] ... line and apt-key add, that is a good sign the docs need a refresh.

Sources and references

Top comments (0)