APT decides where to download packages from based on the sources list: which Debian release, which repositories, and which components. Getting it right means you receive security updates promptly, and don’t accidentally mix releases. Here’s how it works on Debian 11 (bullseye) and Debian 12 (bookworm).

Where the sources are

cat /etc/apt/sources.list
ls /etc/apt/sources.list.d/

Two formats exist:

One-line format (sources.list, *.list):

deb http://deb.debian.org/debian bookworm main contrib non-free non-free-firmware
deb http://deb.debian.org/debian bookworm-updates main contrib non-free non-free-firmware
deb http://security.debian.org/debian-security bookworm-security main contrib non-free non-free-firmware

deb822 format (*.sources, the default on Debian 13 and newer installs):

# /etc/apt/sources.list.d/debian.sources
Types: deb
URIs: http://deb.debian.org/debian
Suites: bookworm bookworm-updates
Components: main contrib non-free non-free-firmware
Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg

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

Use one format consistently, and don’t list the same repository twice.

The parts of a line

Part Meaning
deb / deb-src Binary packages / source packages (only needed for building from source)
URI Mirror address; deb.debian.org redirects to a nearby fast mirror
Suite Release codename (bookworm), plus -updates, -security, -backports
Components main, contrib, non-free, non-free-firmware

Suites (repositories)

Suite Contains Enable?
bookworm The release itself Yes
bookworm-security Security fixes Yes, always
bookworm-updates Important non-security updates (timezone data, etc.) Yes
bookworm-backports Newer versions of selected packages Optional. See Debian backports
stable, testing (aliases) Follow whatever is current Avoid on servers: stable jumps to the next release automatically

Use the codename (bookworm), not stable, so a new Debian release doesn’t upgrade your server unexpectedly. Release upgrades should be deliberate. See upgrade Debian to a new release.

Components

Component Contains
main Free software, fully supported
contrib Free software that depends on non-free software
non-free Software with non-free licences
non-free-firmware Firmware (separate since Debian 12)

Most VPS servers only need main. Firmware rarely matters on virtual machines.

After changing sources

sudo apt update
apt policy                    # which repositories and priorities are active
apt policy nginx              # where a package version would come from

See apt commands and apt update errors.

Third-party repositories (safely)

Vendors (Docker, PostgreSQL, Nginx, NodeSource) provide their own repositories. Add them with a dedicated key limited to that repository:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian bookworm stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list
sudo apt update
  • Avoid the deprecated apt-key add, which trusts a key for all repositories.
  • Only add repositories you trust, since they can replace any package. Pin them if needed. See package pinning.
  • Remove repositories you no longer use, and their keys.

Common errors

Error Cause
NO_PUBKEY … Repository key missing, or not referenced with signed-by
Release file … is not valid yet / expired Server clock wrong. See NTP time sync
does not have a Release file Wrong codename or URL, or an old release moved to archive.debian.org
Target … is configured multiple times Same repository listed twice

Quick reference

Item Value
Files /etc/apt/sources.list, /etc/apt/sources.list.d/*.list / *.sources
Must-have suites bookworm, bookworm-security, bookworm-updates
Default mirror deb.debian.org
Use codenames not stable
Third-party keys /etc/apt/keyrings/ + signed-by=

Related: Debian VPS and add-apt-repository and PPAs (Ubuntu).

  • Debian
  • APT
  • Linux