The main idea behind the script is when you quickly install, use and uninstall some package with apt like this:

$ apt install some-pkg -y
...
$ apt purge --autoremove some-pkg

there could be leftovers. It happens because some of the deps installed along with the package are known as recommended or suggested deps for some other packages in the system hence it can’t be autoremoved. For example

$ apt install alien -y
Reading package lists... Done
Building dependency tree
Reading state information... Done
The following additional packages will be installed:
  ...
Suggested packages:
  ...
The following NEW packages will be installed:
  ...
0 upgraded, 30 newly installed, 0 to remove and 0 not upgraded.
...

$ apt purge --autoremove alien
Reading package lists... Done
Building dependency tree
Reading state information... Done
The following packages will be REMOVED:
  ...
0 upgraded, 0 newly installed, 9 to remove and 0 not upgraded.

Notice 30 packages were installed while only 9 are to be removed.

apt-undo solves the problem providing the exact list of installed packages for an install event from apt log. The generic routine looks like this:

$ apt install some-pkg
  ...
$ apt-undo.sh -i1 | xargs apt purge

Example for the above mentioned alien package install event:

$ apt-undo -i1 | xargs apt purge
Total number of packages: 30
Reading package lists... Done
Building dependency tree
Reading state information... Done
The following packages will be REMOVED:
  ...
0 upgraded, 0 newly installed, 30 to remove and 0 not upgraded.

Notice the script says “Total number of packages: 30” and apt says “30 to remove”.

The script could be safely used to “pop” a series of install events off apt “stack” like apt-undo -i1, then apt-undo -i2 and then apt-undo -i3. But using it with a random install event caution should be taken since some packages installed after the event could depend on it or its deps. Hence blindly undoing the event could remove more packages. At least be sure to check if “Total number of packages: X” and apt’s “Y to remove” show the same number.

By default apt-undo shows numbered summaries for all install events from apt log.

-iN

Pick N‘th install event from apt log. N=1 for the most recent event.

-f <file>

Use a custom log instead of /var/log/apt/history.log. The log could be either a plaintext file or a gz-compressed one (the .gz extension is mandatory). There is no need to use this option to process rotated apt logs since there is -z option for that.

-zN

Operate on N‘th rotated log in default location.

-q

Suppress total number of packages message.

-z and -f are mutually exclusive.

Show summaries for all install events from the default log:

apt-undo.sh

1   lrzsz:amd64 minicom:amd64
2   gocryptfs:amd64
3   qalc:amd64
4   linux-modules-5.8.0-55-generic:amd64 +4
5   zeitgeist-datahub:amd64 zeitgeist-core:amd64 libgee-0.8-2:amd64 +6
...

Show summaries for all install events from the most recent rotated log:

apt-undo.sh -z1

1   libpcre2-32-0:amd64 libselinux1-dev:amd64 libpcre2-dev:amd64 +4
2   libltdl-dev:amd64 autotools-dev:amd64 libsub-override-perl:amd64 +18
3   keepassxc:amd64
4   libpthread-stubs0-dev:amd64 libxcb1-dev:amd64 +5
5   debootstrap:amd64
...

Show summaries for all install events from some file:

# local file
apt-undo.sh -f some.log

1   python3-pyxattr:amd64 rtmpdump:amd64 youtube-dl:amd64
2   libkf5konq6:amd64 libkf5konq-data:amd64 konqueror:amd64 kfind:amd64
3   liblinear4:amd64 nmap:amd64 lua-lpeg:amd64 nmap-common:amd64
4   thunderbird:amd64
5   linux-image-5.8.0-44-generic:amd64 +4
...

# local compressed file
apt-undo.sh -f some.compressed.log.gz

1   libnvidia-compute-455:amd64 libnvidia-compute-455:i386 +19
2   libnvidia-compute-450:amd64 libnvidia-compute-450:i386 +19
3   libnvidia-compute-455:amd64 libnvidia-compute-455:i386 +20
4   libnetaddr-ip-perl:amd64 libsocket6-perl:amd64 geoip-bin:amd64
5   libnvidia-compute-450:amd64 libnvidia-compute-450:i386 +20
...

# remote file
ssh user@host cat /var/log/apt/history.log | apt-undo.sh -f-

1   linux-image-5.8.0-48-generic:amd64 +4
2   byobu:amd64 gawk:amd64 python3-newt:amd64 libsigsegv2:amd64
3   linux-image-5.8.0-45-generic:amd64 +4
4   dctrl-tools:amd64
5   xserver-xorg-video-dummy:amd64 python3-dns:amd64 +32
...

List all packages from the most recent install event:

apt-undo.sh -i1

Total number of packages: 9
zeitgeist-datahub:amd64 zeitgeist-core:amd64 libgee-0.8-2:amd64
libdee-1.0-4:amd64 zeitgeist:amd64 libtelepathy-glib0:amd64
libzeitgeist-2.0-0:amd64 libkeybinder-3.0-0:amd64 synapse:amd64

Check what apt would uninstall while undoing the most recent install event:

apt-undo.sh -i1 | sudo xargs apt purge

Total number of packages: 9
Reading package lists... Done
Building dependency tree
Reading state information... Done
The following packages will be REMOVED:
  libdee-1.0-4* libgee-0.8-2* libkeybinder-3.0-0* libtelepathy-glib0*
  libzeitgeist-2.0-0* synapse* zeitgeist* zeitgeist-core*
  zeitgeist-datahub*
0 upgraded, 0 newly installed, 9 to remove and 0 not upgraded.
After this operation, 6,846 kB disk space will be freed.
Do you want to continue? [Y/n] Abort.

Undo the most recent install event (always be careful with “-y”):

apt-undo.sh -i1 | sudo xargs apt purge -y

Total number of packages: 9
Reading package lists... Done
Building dependency tree
Reading state information... Done
The following packages will be REMOVED:
  libdee-1.0-4* libgee-0.8-2* libkeybinder-3.0-0* libtelepathy-glib0*
  libzeitgeist-2.0-0* synapse* zeitgeist* zeitgeist-core*
  zeitgeist-datahub*
0 upgraded, 0 newly installed, 9 to remove and 0 not upgraded.
After this operation, 6,846 kB disk space will be freed.
(Reading database ... 277775 files and directories currently installed.)
Removing zeitgeist (1.0.2-3ubuntu2) ...
Removing zeitgeist-datahub (1.0.2-3ubuntu2) ...
...