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

> sudo apt install some-pkg
..
> sudo apt purge --autoremove some-pkg

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

> sudo apt-get install alien -y 2>&1 | grep 'newly installed'
0 upgraded, 32 newly installed, 0 to remove and 0 not upgraded.
> apt-get purge -s --autoremove alien 2>&1 | grep 'to remove'
0 upgraded, 0 newly installed, 11 to remove and 0 not upgraded.

Notice, 32 packages were installed while only 11 are to be removed.

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

> sudo apt install some-pkg
..
> sudo apt purge $(apt-undo -i1)

Example for the above mentioned alien package install event:

> apt purge -s $(apt-undo -i1) 2>&1 | grep 'to remove'
Package count: 32
0 upgraded, 0 newly installed, 32 to remove and 0 not upgraded.

Notice, the script says Package count: 32 and apt says 32 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 so on. But using it with a random install event, caution should be taken since some packages installed after the event could depend on it. Hence blindly undoing the event could result in extra packages removal. At least be sure to check if Package count: X and apt’s Y to remove match. When the log belongs to the system apt-undo runs on, it is recommended to always use -i with -t to make sure nothing extra gets removed.

Without any options, show numbered summaries for all install events from the default log.

-f path

Use a custom log (plaintext or gz-compressed) instead of the default one. -z is a special case of -f tailored for gzipped rotated logs. -f - stands for stdin

-h, --help

Show usage

-i N

Show list of packages for N‘th install event

-l

When called without -i, print full package lists instead of summaries

-q

Be less verbose: suppress package count with -i and side-by-side comparison with -t

-t

Requires -i. Check what would apt remove undoing the install event. By default (without -q), print side-by-side comparison of requested vs actual removal lists to stderr. If there are any unrequested packages to be removed, exit with error without printing anything to stdout. This option assumes the log’s origin is the system apt-undo runs on. It is pointless to use -t on foreign logs

-V, --version

Show version

-z N

Operate on N‘th gzipped rotated log in the default location

-z and -f are mutually exclusive.

The following examples are based on apt log populated by such commands run in a debian 12 live session (debian-live-12.5.0-amd64-standard.iso):

sudo apt install openssh-server
sudo apt install emacs --no-install-recommends
sudo apt install elpa-org

Show summaries for all install events from the default log:

> apt-undo
1   elpa-htmlize:amd64 elpa-org:amd64 dh-elpa-helper:amd64
2   emacs:amd64 libgccjit0:amd64 libgif7:amd64 emacs-gtk:amd64 +4
3   openssh-server:amd64 runit-helper:amd64 openssh-sftp-server:amd64

The same with summaries expanded to full lists:

> apt-undo -l
1   elpa-htmlize:amd64 elpa-org:amd64 dh-elpa-helper:amd64
2   emacs:amd64 libgccjit0:amd64 libgif7:amd64 emacs-gtk:amd64 install-info:amd64 emacs-el:amd64 emacs-common:amd64 emacs-bin-common:amd64
3   openssh-server:amd64 runit-helper:amd64 openssh-sftp-server:amd64

List all packages from the most recent install event:

> apt-undo -i1
Package count: 3
elpa-htmlize:amd64 elpa-org:amd64 dh-elpa-helper:amd64

Check what apt would remove while undoing the event. Notice, the packages listed in side-by-side comparison match:

> apt-undo -i1 -t
Package count: 3

dh-elpa-helper:amd64  dh-elpa-helper:amd64
elpa-htmlize:amd64    elpa-htmlize:amd64
elpa-org:amd64        elpa-org:amd64

elpa-htmlize:amd64 elpa-org:amd64 dh-elpa-helper:amd64

Here is what happens when there are more packages to remove than we asked for:

> apt-undo -i2 -t
Package count: 8

--                      elpa-org:amd64
emacs:amd64             emacs:amd64
emacs-bin-common:amd64  emacs-bin-common:amd64
emacs-common:amd64      emacs-common:amd64
emacs-el:amd64          emacs-el:amd64
emacs-gtk:amd64         emacs-gtk:amd64
install-info:amd64      install-info:amd64
libgccjit0:amd64        libgccjit0:amd64
libgif7:amd64           libgif7:amd64

error: Extra packages to be removed

Undo the most recent install event (dry run):

> sudo apt purge --assume-no $(apt-undo -i1 -t)
Package count: 3

dh-elpa-helper:amd64  dh-elpa-helper:amd64
elpa-htmlize:amd64    elpa-htmlize:amd64
elpa-org:amd64        elpa-org:amd64

Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following packages will be REMOVED:
  dh-elpa-helper* elpa-htmlize* elpa-org*
0 upgraded, 0 newly installed, 3 to remove and 0 not upgraded.
After this operation, 333 kB disk space will be freed.
Do you want to continue? [Y/n] N
Abort.