I use the Advanced Package Tool (APT) for installing, updating, removing, and searching software on Debian, Ubuntu, or derivatives. This guide provides a clear way to complete these tasks and verify them.

Goal

By the end, you’ll have used APT to install, update, remove, and search for packages, knowing how to confirm each step and fix common failures.

Success criteria: You can run apt install, apt update, apt upgrade, apt remove, and apt search from the command line and interpret the output. You can confirm a package is installed and working.

Scope: This guide covers everyday APT tasks on a single machine. It excludes adding third-party repositories, pinning, or building packages from source.

Assumptions: Debian, Ubuntu, or derivatives on amd64 or arm64. You need a terminal with root or sudo access. Examples include real package names like nginx for easy copying.

Prerequisites

Required knowledge:

  • Basic use of the terminal (running commands, reading output).
  • How to run privileged commands (e.g., sudo).

Required tools:

  • APT (Advanced Package Tool), provided by the apt package. Default on Debian, Ubuntu, and other Debian derivatives.
  • A supported release (e.g. Debian 11+, Ubuntu 20.04 LTS or newer). Check with lsb_release -a or /etc/os-release.

Required access:

  • Ability to run commands as root (e.g., sudo); installing and removing packages require it.

Steps

Step 1: Refresh package lists

Before installing or upgrading, refresh the local copy of repository metadata so APT knows the latest versions and dependencies.

sudo apt update

Expected output: Lines such as “Hit,” “Get,” or “Ign” per repository, then “Reading package lists… Done” and possibly “Building dependency tree… Done.” Exit code 0 indicates success. Warnings about missing GPG keys or repository errors suggest configuration issues; see Troubleshooting.

Step 2: Install a package

Install a single package and its dependencies. Example: install the nginx web server.

sudo apt install nginx

APT will list the package(s) to be installed and the extra disk space needed, then prompt for confirmation (Y/n). Answer Y and press Enter. If you want to avoid the prompt (e.g., in scripts), use -y:

sudo apt install -y nginx

Expected output: Download progress, “Unpacking…” and “Setting up…” lines, then “Processing triggers…” if any. The command exits 0 when the install completes. The package and its dependencies are then installed.

Step 3: Confirm the package is installed

Check that the package is present and, if it provides a command, that the command runs.

apt list --installed | grep nginx
dpkg -L nginx

Optionally run the program (e.g., nginx -v or which nginx) to confirm it is on your PATH and working.

Step 4: Upgrade installed packages

To upgrade all installed packages to the versions offered by your configured repositories, run:

sudo apt update
sudo apt upgrade

apt update refreshes package lists; apt upgrade upgrades all packages that have a candidate version. You will see a summary of packages to upgrade and a confirmation prompt. Use -y to skip the prompt when appropriate.

Expected output: List of packages to upgrade, download, unpack, then “Setting up…” for each. Exit code 0 indicates success. If additional packages are to be removed or installed, review the summary before confirming.

For a full release upgrade (e.g., a minor version bump), use sudo apt full-upgrade when your distro’s documentation supports it. Warning: full-upgrade can add or remove packages to satisfy dependencies; always review the summary before confirming.

Step 5: Remove a package

Choose one:

  • Remove only (keep config): Use remove if you might reinstall the package later and want to keep its configuration files.
  • Remove and delete config: Use purge to remove the package and its configuration files.

Remove but keep config:

sudo apt remove nginx

Remove and delete config:

sudo apt purge nginx

Expected output: APT lists packages for removal and asks for confirmation. Once confirmed, the package is removed. Dependencies not needed anymore aren’t removed automatically; run sudo apt autoremove to clean up (see Step 6).

Step 6: Remove unused dependencies (optional)

After removing packages, leftover dependencies may remain. To delete unused dependency-only packages:

sudo apt autoremove

Review the list before confirming; running this step periodically frees disk space.

Step 7: Search for packages

To find packages by name or description:

apt search nginx

Expected output: A list of package names and short descriptions. Install the desired package with sudo apt install <package-name>.

To show detailed information about a specific package (version, description, dependencies):

apt show nginx

Verification

  • Install: apt list --installed | grep <package> shows the package; the program runs (e.g., nginx -v or which <command>).
  • Upgrade: apt list --upgradable is empty after a successful full upgrade, or shows only packages you chose not to upgrade.
  • Remove: apt list --installed | grep <package> shows nothing; the binary is no longer on PATH.
  • Search: apt search <term> returns matching packages; apt show <package> shows details for one package.

If any of these checks fail, re-run the corresponding step and check the command output for errors, then see Troubleshooting.

Troubleshooting

Problem: “Unable to locate package

Symptoms: apt install <name> reports “Unable to locate package” or “Package has no installation candidate.”

Solution: Refresh package lists with sudo apt update, then retry. If it still fails, the package name might be wrong (use apt search <term>), or the package isn’t in enabled repositories. Verify the correct repository for your release.

If that doesn’t work: Confirm your architecture and release with dpkg --print-architecture and lsb_release -a. Some packages are only in backports or non-free; see your distro’s documentation on enabling those.

Problem: “The following packages have unmet dependencies.”

Symptoms: APT refuses to install or upgrade, listing broken or unmet dependencies.

Solution: Run sudo apt --fix-broken install. APT will try to install missing dependencies or fix broken states. If it prompts to install or remove packages, read the summary and confirm if the plan is acceptable.

If that doesn’t work: Check for held packages with apt-mark showhold. Unhold only if you understand why. If from a third-party repo, ensure it’s correct for your release and run sudo apt update.

Problem: GPG or repository errors during apt update

Symptoms: Warnings like “The following signatures couldn’t be verified” or “Repository … does not have a Release file.”

Solution: Repositories often misconfigure, or GPG keys are missing or expired. For official repos, verify your release support and sources list; for third-party repos, follow project instructions to add keys and repos. To troubleshoot, temporarily comment out the problematic line in /etc/apt/sources.list or /etc/apt/sources.list.d/.

If that doesn’t work: Restore the default sources for your release (the “sources.list” file in Debian and the “Repositories” page in Ubuntu) and add third-party repos one at a time to identify the failing one.

Problem: Could not get lock /var/lib/dpkg/lock

Symptoms: APT or dpkg reports that a lock file is held by another process.

Solution: Another APT or dpkg process is running (e.g., Software Updater, unattended-upgrades). Wait for it to finish, or close the other tool. Do not remove the lock file while another process is using it.

If that doesn’t work: If you are sure no other APT/dpkg process is running (check with ps aux | grep -E 'apt|dpkg'), you can remove the lock with sudo rm /var/lib/dpkg/lock and sudo rm /var/lib/dpkg/lock-frontend and then run sudo dpkg --configure -a and sudo apt update. Use only when you understand the risk; interrupting dpkg can leave the database inconsistent.

Rollback

APT doesn’t keep multiple package versions by default. To “undo” an install, run sudo apt remove <package> or sudo apt purge <package>. To revert an upgrade, pin or install an older version from cache or snapshot; beyond this guide’s scope. Backup before major upgrades.

Related Content

References