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.

```bash
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.

```bash
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`:

```bash
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.

```bash
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:

```bash
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:

```bash
sudo apt remove nginx
```

Remove and delete config:

```bash
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:

```bash
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:

```bash
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):

```bash
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

* [Debian package management documentation][debian-apt]: official APT and dpkg documentation for Debian.
* [Ubuntu server guide: Package management][ubuntu-pkg]: Ubuntu's guide to APT and repositories.
* For conceptual background on what a package manager is and how it fits with repositories and dependencies, see [How Do I Use DNF?][dnf-howto] (same ideas, different distro).

## References

* [Debian package management documentation][debian-apt]: APT and dpkg reference for Debian.
* [Ubuntu server guide: Package management][ubuntu-pkg]: Ubuntu's package management and repository configuration.
* [apt(8) man page][apt-man]: command-line options for `apt`.

[debian-apt]: https://www.debian.org/doc/manuals/debian-reference/ch02.en.html
[ubuntu-pkg]: https://ubuntu.com/server/docs/package-management
[apt-man]: https://manpages.debian.org/apt
[dnf-howto]: /blog/2026/02/28/how-do-i-use-dnf/