Difference Between apt-get upgrade and apt-get dist-upgrade

1. Introduction

Who else gets a kick whenever we get an update to an existing package or software? This is a familiar feeling among system administrators and users of Linux systems worldwide. However, managing packages on Debian-based systems can be challenging, as we face various options. Among these options are the apt-get upgrade and apt-get dist-upgrade commands, which seemingly do the same thing but carry out different purposes.

In this tutorial, we’ll explore the major differences between apt-get upgrade and apt-get dist-upgrade, as well as their characteristics, use cases, and common pitfalls.

2. Understanding apt-get upgrade

To understand the differences, we should first understand how apt-get upgrade works. It is a command we primarily use to upgrade packages to newer versions. It works by fetching the latest package list from repositories defined in the /etc/apt/sources.list file and comparing them with the version currently installed.

If a newer version is available, this command attempts to install it:

$ sudo apt-get update && apt-get upgrade 
[sudo] password for user: 
Get:1 http://security.ubuntu.com/ubuntu focal-security InRelease [128 kB] 
Get:2 https://packages.microsoft.com/repos/code stable InRelease [3,590 B] 
... 
Fetched 21.6 MB in 35s (612 kB/s) 
Reading package lists... Done
Building dependency tree       
...
The following packages have been kept back:
  linux-generic-hwe-20.04 linux-headers-generic-hwe-20.04 linux-image-generic-hwe-20.04 date-manager update-manager-core
The following packages will be upgraded:
  accountsservice
...
498 upgraded, 0 newly installed, 0 to remove and 10 not upgraded.
Need to get 938 MB of archives.
...
Do you want to continue? [Y/n]
...

As mentioned, we fetch the latest package list from the /etc/apt/sources.list file using the apt-get update command. When it gets these package lists, it compares them with the installed version. Afterwards, it carries on the installation if a newer version is available.

2.1. Characteristics

Let’s look at some of the defining features of apt-get upgrade:

• Safe Upgrades: This command is widely known for its conservative approach to installation. It’ll not remove existing packages or install new ones. Hence, using this command during an upgrade does not introduce instability to your system.
• No Dependency Changes: When apt-get upgrade encounters a package with a new dependency, it does not upgrade that package. Instead, it leaves the package in its current state.

For example, if a package foo version 1.0 is installed and version 1.1 is available but requires a new dependency bar, the apt-get upgrade will not upgrade the bar.

3. Understanding apt-get dist-upgrade

Conversely, apt-get dist-upgrade is a superset of apt-get upgrade. This means that it not only upgrades the installed package but also attempts to handle any dependency change automatically.

Consequently, it can install new packages or remove existing ones if required to complete the upgrade process:

$ sudo apt-get --simulate dist-upgrade
[sudo] password for user: 
Reading package lists... Done
Building dependency tree       
...
Use 'sudo apt autoremove' to remove them.
The following NEW packages will be installed:
  linux-headers-5.15.0-119-generic linux-hwe-5.15-headers-5.15.0-119 linux-image-5.15.0-119-generic
...
The following packages will be upgraded:
  accountsservice amd64-microcode apache2 apache2-bin apache2-data apache2-utils apparmor apport apport-gtk apt apt-transport-https apt-utils avahi-autoipd avahi-daemon
  avahi-utils base-files bind9-dnsutils bind9-host bind9-libs binutils binutils-common
...

Did we notice the difference in the outputs? In the apt-get upgrade output, we received a message that the Linux headers and images would not be installed, but the opposite happens here.

Can we guess why this is so? The dist-upgrade allows the installation of new packages, which is required to upgrade those packages to work.

3.1. Characteristics

Just like apt-get upgrade, this command has some defining characteristics as well:

• Dependency Resolution: dist-upgrade can resolve dependency issues. This means that it can install new dependencies or remove existing packages to complete an upgrade.
• Potential System Impact: This command can introduce significant changes to the system by affecting the dependency structure. It could install unwanted software or remove critical packages.

In the same vein, let’s use the same example as the previous command. If a package foo v1.0 requires a dependency bar for v1.1 to be installed during the upgrade process, dist-upgrade will attempt to install this newer version. If, during upgrading, it realizes that another package baz conflicts with the upgrade, it might remove it to proceed with the upgrade.

4. Summary of Differences

Let’s look at a summarized view of the differences between apt-get upgrade and apt-get dist-upgrade:

Now that we know their differences let’s look at their use cases.

5. Use Cases

As we mentioned earlier, both commands seemingly do the same thing. However, both have specific use cases, and we’ll explore when to use them.

We use apt-get update in situations where system stability is the priority. This can be the case for production servers where uptime and reliability are crucial and disruptions to the stability of packages can be detrimental. It is safer to use this command as it performs minimal changes during the upgrade process.

Conversely, we use apt-get dist-upgrade when we might need to resolve dependency issues during package upgrades. Especially in packages that are being held back by apt-get upgrade. Additionally, dist-upgrade is useful when moving to a new version of a Linux’s distribution, as it ensures all packages are compatible with the new release.

5.1. Common Pitfalls With apt-get dist-upgrade and apt-get upgrade

While these commands are essential to system administrators and users, we might still encounter some pitfalls when we use them.

One of the common pitfalls, particularly in apt-get dist-upgrade are broken packages. These mainly occur due to conflicts in the upgrade process.

Another pitfall we might encounter, this time in using apt-get upgrade, are held-back packages. As we know, apt-get upgrade does not allow the additional installation or removal of a dependency or package during an upgrade. If the upgrade requires a new package or dependency, this can halt the process. This can pose a problem if the upgrade process involves a lot of packages.

6. Conclusion

In this article, we discussed the differences between apt-get upgrade and apt-get dist-upgrade. We established that while both commands seemingly perform the same function, their ability to handle dependency during the upgrade differs. Additionally, we explored their characteristics and looked at some use cases. Lastly, we identified some common pitfalls when using these commands.