← Full reference

apt and dpkg

Packages on Debian and Ubuntu — install, remove, search, versions, which package owns a file

On Debian and Ubuntu, software is installed as .deb packages. dpkg is the low-level tool: it installs and removes individual .deb files and keeps the database of installed packages, but doesn't download dependencies itself. apt (and the older apt-get, apt-cache) works on top of dpkg: it fetches packages from repositories and pulls in dependencies and updates on its own. In practice you install and remove with apt, and use dpkg for questions like "what is installed?" and "where did this file come from?".

Syntax

apt [options] command [package…]
apt-get [options] command [package…]     # stable output — for scripts
apt-cache command [package…]
dpkg [options] action [package|file…]

Installing and removing require root (sudo). Searching and viewing work for any user.

apt: install and remove

CommandWhat it does
apt updatedownload fresh package lists from the repositories — do this before install
apt install package…install with dependencies; if already installed — upgrade to the latest version
apt install package=versioninstall a specific version
apt install ./file.debinstall a local .deb, pulling in dependencies (the path must start with ./ or /)
apt reinstall packagereinstall
apt remove packageremove the program, keeping its configuration files
apt purge packageremove together with its configuration
apt autoremoveremove dependencies nothing needs anymore
apt upgradeupgrade everything installed (without removing packages)
apt full-upgradeupgrade everything, allowing packages to be removed and installed to satisfy dependencies
apt download packageonly download the .deb into the current directory
apt cleanclear the cache of downloaded .deb files in /var/cache/apt/archives

apt: search and information

CommandWhat it does
apt search wordsearch names and descriptions; --names-only — names only
apt show packagedescription, version, size, dependencies
apt list --installedinstalled packages
apt list --upgradablewhat can be upgraded (after apt update)
apt-cache policy packageinstalled version, install candidate and which repositories they come from
apt-cache madison packageall available versions per repository
apt-cache depends packagewhat the package depends on
apt-cache rdepends packagewhich packages depend on this one

apt and apt-get options

OptionWhat it does
-yanswer "yes" to all questions — for scripts
-s, --dry-runonly show what would be done
-q / -qqquieter / almost no output
--no-install-recommendsdon't install recommended packages — less clutter
-f installfix broken dependencies
--only-upgradewith install: only upgrade if the package is already installed

apt-mark

CommandWhat it does
apt-mark hold package / unholdblock / allow upgrading the package
apt-mark showholdpackages held back from upgrades
apt-mark showmanual / showautoinstalled manually / as dependencies (autoremove will remove those)
apt-mark manual packagemark as manually installed so autoremove leaves it alone

dpkg

CommandWhat it does
dpkg -l [pattern]list packages with state and version: dpkg -l 'python3*'
dpkg -L packagewhich files the package installed
dpkg -S pathwhich package owns a file: dpkg -S /usr/bin/flock
dpkg -s packagestatus and description of an installed package
dpkg -i file.debinstall a .deb (doesn't download dependencies)
dpkg -r package / dpkg -P packageremove / remove with configuration
dpkg -c file.deb / dpkg -I file.debcontents / metadata of a .deb file without installing it
dpkg --configure -afinish configuring packages after an interrupted install
dpkg-query -W -f='${Package} ${Version}\n'list in a custom format

State in dpkg -l

The first two letters of a line: desired action and current state.

CodeMeaning
iiinstalled and working
rcremoved (remove), but configuration files remain — purge cleans them up
unnot installed
hiinstalled and held (apt-mark hold)
iU / iFunpacked but not configured / configuration failed — fixed by dpkg --configure -a

Examples

# refresh the lists and install a package without prompts
apt update && apt install -y tree

# in Dockerfiles and scripts — apt-get, no recommends and no prompts
DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends curl

# which version is installed and what is available
apt-cache policy bash

# is the package installed (for a script: exit code 0 — yes)
dpkg -s jq >/dev/null 2>&1 && echo "jq is installed"

# find the package a command came from
dpkg -S "$(command -v flock)"

# where the package's files are, e.g. its configs
dpkg -L cron | grep ^/etc

# list installed packages with versions
dpkg-query -W -f='${Package}\t${Version}\n' | head

# the largest packages (size in KiB)
dpkg-query -W -f='${Installed-Size}\t${Package}\n' | sort -n | tail -5

# packages removed without purge — with leftover configs
dpkg -l | awk '/^rc/ { print $2 }'

# see what an install would do without changing anything
apt install -s nginx

# freeze the version
apt-mark hold nginx

Pitfalls

  • Without network access you can't install anything. The sandbox may have no internet access: apt update prints Temporary failure resolving and still returns exit code 0, and apt install answers Unable to locate package or has no installation candidate. dpkg -l/-L/-S/-s and apt-cache policy still work — they read the local database.
  • Unable to locate package often means "no apt update was run". Docker images have the package lists deleted to save space, so you need to download them first.
  • remove keeps configs. The package stays in dpkg -l with status rc, and the files in /etc remain in place. To wipe everything, use purge.
  • apt is not for scripts. Its output can change between versions, as it warns itself: WARNING: apt does not have a stable CLI interface. In scripts and Dockerfiles use apt-get and apt-cache.
  • Prompts during install hang a script. You need -y and DEBIAN_FRONTEND=noninteractive — otherwise apt waits for a "Y/n" answer or for debconf questions.
  • dpkg -i doesn't install dependencies. If some are missing, the package stays unconfigured. Install local files with apt install ./file.deb or fix it afterwards with apt -f install.
  • apt install package upgrades an already installed package if a newer version exists. To prevent that, hold it with apt-mark hold.
  • could not get lock /var/lib/dpkg/lock-frontend — another apt or dpkg is already running (often automatic updates). Wait for it to finish rather than deleting the lock files.

See also

which · sudo · service · curl · env