Manage packages with APT

On Debian, Ubuntu and their derivatives, APT is the tool that installs, updates and removes software, handling dependencies automatically. This guide covers the everyday commands, how repositories work (with the newer deb822 format), the safe addition of a third-party repository through a GPG key, and the troubleshooting of frequent errors. It is written for beginner to intermediate administrators on Debian/Ubuntu. For the other families, see dnf (Red Hat, Fedora), Pacman (Arch) or APK (Alpine).

What you will learn

• Use the essential APT commands (install, update, remove)
• Understand repositories and the modern deb822 format
• Add a third-party repository with its GPG key, without apt-key
• Pin a version and manage priorities
• Troubleshoot common APT errors

Prerequisites

• A Debian or Ubuntu machine (the examples use Debian 13 "trixie" and Ubuntu 24.04)
• An account with sudo rights
• Some basics of the Linux command line

apt or apt-get: which one to use

Two families of commands coexist and cause confusion. apt is the modern, friendly interface, designed for interactive use: readable output, a progress bar, colours since APT 3.0 (Debian 13). apt-get and apt-cache are the historical commands, with a stable output.

The rule is simple: apt at the keyboard, apt-get in scripts. APT reminds you itself if you script apt:

WARNING: apt does not have a stable CLI interface. Use with caution in scripts.

In other words, the output of apt can change from one version to the next: a script that parses it will break. In a playbook or a Dockerfile, prefer apt-get install -y.

The essential APT commands

Here are the commands you will use every day. Each one acts on the local cache of metadata or on the installed packages.

• Refresh the package list:

  sudo apt update

  This command queries the repositories and downloads the metadata of the available versions, without installing anything. It is the prerequisite for any installation. Important: apt update does not update your software, only the local cache.

• Update the installed packages:

  sudo apt upgrade

  Updates the installed packages to their latest version, without removing any or adding new ones.

• Update, including dependency changes:

  sudo apt full-upgrade

  More thorough than upgrade, it agrees to remove or add packages to resolve dependencies. Useful during a version upgrade, and the summary deserves a careful read before you confirm.

• Install a package (and its dependencies automatically):

  sudo apt install nginx

  To force a specific version, first list the available versions, then pass the one you want after an =:

  apt list -a nginx                          # versions offered by the repositories
  sudo apt install nginx=1.26.3-3+deb13u9    # version recorded on Debian 13, 30 September 2026

• Remove a package, keeping its configuration or not:

  sudo apt remove nginx     # keeps the files in /etc
  sudo apt purge nginx      # also removes the configuration

• Remove dependencies that are no longer needed:

  sudo apt autoremove

• Search for and inspect a package:

  apt search <keyword>      # searches the local cache
  apt show nginx            # version, size, dependencies, description

• Clean the downloaded archives:

  sudo apt clean            # removes all of /var/cache/apt/archives/
  sudo apt autoclean        # removes only the obsolete .deb files

Check what is installed

After an installation, apt list --installed | grep nginx confirms the package is present and its version. To see where a version comes from, use apt policy nginx (detailed below).

How APT finds packages: repositories

APT downloads packages from repositories declared in configuration files. Two formats coexist today.

The modern deb822 format (.sources)

The deb822 format stores repositories in .sources files under /etc/apt/sources.list.d/, easier to read and to automate. Ubuntu 24.04 uses it by default (ubuntu.sources), as do the official Debian images since Debian 12. On a Debian 13 image, recorded on 30 September 2026, the file /etc/apt/sources.list.d/debian.sources holds two blocks, one for the distribution, the other for the security fixes:

Types: deb
URIs: http://deb.debian.org/debian
Suites: trixie trixie-updates
Components: main
Signed-By: /usr/share/keyrings/debian-archive-keyring.pgp

Types: deb
URIs: http://deb.debian.org/debian-security
Suites: trixie-security
Components: main
Signed-By: /usr/share/keyrings/debian-archive-keyring.pgp

Each field is explicit: Types (deb for binaries), URIs (the server), Suites (the release, here trixie, and its variants), Components (the sections, to which you add contrib or non-free-firmware when needed) and above all Signed-By, which ties the repository to its signing key. That last field is what secures the chain.

The old one-line format (sources.list)

The historical format, one line per repository in /etc/apt/sources.list, is still accepted:

deb http://deb.debian.org/debian trixie main contrib non-free-firmware

You still come across it everywhere, but deb822 is gradually replacing it. For a new repository, prefer the .sources format.

A useful clarification, because many articles exaggerate it: the one-line format is deprecated, not removed, and the Debian 13 manual page announces a removal not before 2029. There is no hurry to convert an existing server. When you decide to do it, APT 3.0 provides the apt modernize-sources command, which converts the files and backs up the originals. It is covered, with its limits, in the Debian 13 "Trixie" guide (in French).

Suites and components: two different axes

A repository is split along two axes that are easy to mix up. The suite names the release of the distribution and its update streams; the component sorts software by licence or maintenance model. Security fixes and backports are therefore suites, not components:

Axis	Value	Content
Suite	trixie (Debian 13), noble (Ubuntu 24.04)	the distribution as released
Suite	trixie-updates, noble-updates	fixes published after the release
Suite	trixie-security, noble-security	security updates
Suite	trixie-backports, noble-backports	recent versions backported to stable
Debian component	main, contrib, non-free, non-free-firmware	supported free software, free software depending on non-free parts, non-free, firmware
Ubuntu component	main, restricted, universe, multiverse	supported by Canonical, proprietary drivers, community, community non-free

Swipe to see more

After any change to the sources, reload the index:

sudo apt update

Add a third-party repository safely

Installing software missing from the official repositories (Docker, Node.js, etc.) requires adding a third-party repository. The golden rule: always verify the signature of the packages with the publisher's GPG key.

apt-key is gone

Old tutorials use apt-key add. This command has been deprecated since Debian 11 and was removed with APT 3.0. Recorded on 30 September 2026: it still exists, with a warning, on Debian 12 (APT 2.6) and Ubuntu 24.04 (APT 2.8), but the binary has disappeared from Debian 13 (APT 3.0) and from Ubuntu Server 26.04 (APT 3.2, in French): old scripts no longer print a warning there, they fail. So never add a key to the global keyring again, even where the command still answers: use a dedicated keyring per repository and the Signed-By field.

The correct method takes two steps. First, download the publisher's key into a dedicated keyring:

curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key \
  | sudo gpg --dearmor -o /usr/share/keyrings/nodesource.gpg

gpg --dearmor converts the key to the expected binary format. Then declare the repository in deb822, pointing Signed-By at that keyring:

/etc/apt/sources.list.d/nodesource.sources

Types: deb
URIs: https://deb.nodesource.com/node_22.x
Suites: nodistro
Components: main
Signed-By: /usr/share/keyrings/nodesource.gpg

A sudo apt update validates the configuration: if the key matches, the repository's packages become available; otherwise APT rejects the repository rather than install an unverified package.

apt-add-repository and PPAs (Ubuntu)

On Ubuntu and its derivatives, the apt-add-repository command (package software-properties-common) automates adding a repository, in particular the PPAs hosted on Launchpad:

sudo apt-add-repository ppa:graphics-drivers/ppa
sudo apt update

To remove a repository or a PPA, add --remove. PPAs do not exist on standard Debian; only add PPAs from trusted publishers, because they have the same level of access as the official repositories.

Control versions

APT lets you freeze a version or arbitrate between several sources, which is precious on a production server.

See which version will be installed with apt policy

apt policy bash

bash:
  Installed: 5.2.37-2+b9
  Candidate: 5.2.37-2+b9
  Version table:
 *** 5.2.37-2+b9 500
        500 http://deb.debian.org/debian trixie/main amd64 Packages
        100 /var/lib/dpkg/status

Installed is the version present, Candidate the one that would be installed, and the table lists the available versions with their priority and origin. Indispensable to understand why APT picks a given version.

Force a priority with pinning

In /etc/apt/preferences.d/, a preferences file imposes a priority on a source. Example to favour Node.js from the NodeSource repository:

/etc/apt/preferences.d/nodejs

Package: nodejs
Pin: origin deb.nodesource.com
Pin-Priority: 600

A Pin-Priority above 500 makes the source preferred; from 1000 upwards, the apt_preferences(5) manual even allows going back to an older version (downgrade), and common practice writes 1001. Handle with care: a badly tuned pin can block security updates.

Lock a package with apt-mark

To prevent a package from being updated (for instance a kernel or a validated database):

sudo apt-mark hold postgresql-17   # locks
apt-mark showhold                  # lists the locked packages
sudo apt-mark unhold postgresql-17 # unlocks

Security and good practice

Package management is a sensitive point in a server's security. A few rules limit the risks.

• Apply updates regularly. A frequent sudo apt update && sudo apt upgrade applies the security fixes. On an exposed server, this is not negotiable.

• Only add trusted repositories. Every third-party repository can install code with root rights. Check the publisher and the GPG key, and limit the number of external sources.

• Automate security fixes with the unattended-upgrades package, which applies critical updates on its own:

  sudo apt install unattended-upgrades
  sudo dpkg-reconfigure --priority=low unattended-upgrades

• Version /etc/apt/. Before a big operation, back up your repository configuration. The etckeeper tool (in French) automatically versions /etc in a Git repository (in French), which lets you roll back after a risky change.

Troubleshooting

Even when used well, APT can get stuck. Here are the most frequent errors and their fix.

Symptom	Likely cause	Solution
dpkg was interrupted	Interrupted installation	sudo dpkg --configure -a
Unmet dependencies	Broken packages	sudo apt --fix-broken install
Corrupted cache, read errors	Damaged archives	sudo apt clean && sudo apt update
NO_PUBKEY on update	Repository GPG key missing	Reinstall the key as a Signed-By keyring
404 Not Found on update	Invalid URL or suite in the sources	Fix the .sources or the sources.list
E: Unable to locate package <name> and apt policy <name> completely silent	The component index (often universe) was never downloaded	sudo apt update, and check that the component is listed in the sources
Package impossible to remove	Package in an unstable state	sudo dpkg --remove --force-remove-reinstreq <package>

Swipe to see more

To understand the origin of an incident, the APT logs trace every operation:

cat /var/log/apt/history.log    # packages installed, updated, removed
cat /var/log/apt/term.log       # detailed output of the operations

The NO_PUBKEY trap

A classic temptation: "fixing" a NO_PUBKEY with apt-key adv --recv-keys. This command no longer exists since APT 3.0 (Debian 13, Ubuntu 26.04), and it puts the key back in the global keyring wherever it still answers. The right answer is to download the key again from the publisher into /usr/share/keyrings/ and reference it through Signed-By, as seen above.

Hands-on practice

Put these moves into practice on a disposable VM: install a package with apt, freeze it with a hold so that an update ignores it, and identify which package owns a file with dpkg.

Guided lab Practice

Learn how to do it

Manage Debian packages with apt and dpkg

$ dsoxlab run lfcs-package-apt

Environment: VM·Duration: ~20 min

How it is checked: the state of the system is checked after a reboot, not the command you typed.

First time? What DSOXLab is and how to install it

DSOXLab is the command line that prepares a disposable environment (an isolated shell or a VM), runs the lab scenario, then checks the real state of the system and computes a score. Nothing is installed or broken on your workstation.

It needs Python 3.11 or later, uv or pipx, and git. The installation guide details these prerequisites; on Windows, or on a Mac without Python, use the appliance instead.

This lab starts virtual machines: it also needs ansible-playbook, a hypervisor (KVM or Incus), Terraform and hardware virtualization (/dev/kvm), which inside a VirtualBox VM means nested virtualization. The first time, dsoxlab start lfcs-package-apt checks all of it before creating the machines. Prepare your machine for vm labs.

Install the CLI and add the catalogue, once:

uv tool install dsoxlab   # or: pipx install dsoxlab
dsoxlab catalog add https://github.com/stephrobert/linux-dsoxlab-training

Before you run the lab, check:

• DSOXLab installed
• catalogue available
• compatible environment (isolated shell or VM)

To check, nothing is probed from this page: run dsoxlab doctor. Read the diagnosis

Run this lab, then validate your work:

dsoxlab run lfcs-package-apt
dsoxlab check lfcs-package-apt

See every lab: dsoxlab list-labs. Track your progress: dsoxlab progress. The full dsoxlab guide covers scoring and the pitfalls.

Key points

• apt at the keyboard, apt-get/apt-cache in scripts (stable interface).
• apt update refreshes the cache; apt upgrade updates the installed packages.
• Repositories are now declared in deb822 (.sources), with a Signed-By field.
• apt-key is gone since APT 3.0: a GPG key goes into a dedicated keyring, referenced by Signed-By.
• apt policy shows which version will be installed; apt-mark hold locks a package.
• A NO_PUBKEY is solved by reinstalling the key, never with apt-key.

Knowledge check

Check that the essentials of this guide are acquired. The questions only cover what has just been explained here.

Knowledge check

Check what you have learned with this interactive quiz

6 questions

6 min

70% to pass

How it works

• The timer starts when you click Start
• Multiple choice, true/false and short answer questions
• You can move between questions
• Detailed results are shown at the end

Start the quiz

Starts the quiz and the timer

×

See in the glossary →