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
| Command | What it does |
|---|
apt update | download 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=version | install a specific version |
apt install ./file.deb | install a local .deb, pulling in dependencies (the path must start with ./ or /) |
apt reinstall package | reinstall |
apt remove package | remove the program, keeping its configuration files |
apt purge package | remove together with its configuration |
apt autoremove | remove dependencies nothing needs anymore |
apt upgrade | upgrade everything installed (without removing packages) |
apt full-upgrade | upgrade everything, allowing packages to be removed and installed to satisfy dependencies |
apt download package | only download the .deb into the current directory |
apt clean | clear the cache of downloaded .deb files in /var/cache/apt/archives |
apt: search and information
| Command | What it does |
|---|
apt search word | search names and descriptions; --names-only — names only |
apt show package | description, version, size, dependencies |
apt list --installed | installed packages |
apt list --upgradable | what can be upgraded (after apt update) |
apt-cache policy package | installed version, install candidate and which repositories they come from |
apt-cache madison package | all available versions per repository |
apt-cache depends package | what the package depends on |
apt-cache rdepends package | which packages depend on this one |
apt and apt-get options
| Option | What it does |
|---|
-y | answer "yes" to all questions — for scripts |
-s, --dry-run | only show what would be done |
-q / -qq | quieter / almost no output |
--no-install-recommends | don't install recommended packages — less clutter |
-f install | fix broken dependencies |
--only-upgrade | with install: only upgrade if the package is already installed |
apt-mark
| Command | What it does |
|---|
apt-mark hold package / unhold | block / allow upgrading the package |
apt-mark showhold | packages held back from upgrades |
apt-mark showmanual / showauto | installed manually / as dependencies (autoremove will remove those) |
apt-mark manual package | mark as manually installed so autoremove leaves it alone |
dpkg
| Command | What it does |
|---|
dpkg -l [pattern] | list packages with state and version: dpkg -l 'python3*' |
dpkg -L package | which files the package installed |
dpkg -S path | which package owns a file: dpkg -S /usr/bin/flock |
dpkg -s package | status and description of an installed package |
dpkg -i file.deb | install a .deb (doesn't download dependencies) |
dpkg -r package / dpkg -P package | remove / remove with configuration |
dpkg -c file.deb / dpkg -I file.deb | contents / metadata of a .deb file without installing it |
dpkg --configure -a | finish 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.
| Code | Meaning |
|---|
ii | installed and working |
rc | removed (remove), but configuration files remain — purge cleans them up |
un | not installed |
hi | installed and held (apt-mark hold) |
iU / iF | unpacked 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