How to compare Docker images with container-diff

How to use container-diff

Container-diff provides a range of different functions, all available from a command line. Use the container-diff command, followed by various flags, to define what types of differences you want to see between the images. This command displays how changes to a Dockerfile could affect the Docker container itself.

The main flags are analyze and diff. The analyze flag is used against a single container. When run as container-diff analyze <container image>, where <container image> is an ID, tarball or repository URL, it returns the container's size. However, admins can apply several additional modifiers that include the following:

• --type=apt reports on what OS-level packages are installed in the image.
• --type=file reports on every file in the image, along with its size.
• --type=history prints the commands that generate Docker layers within the image, reflecting a rough version of the Dockerfile.
• --type=node reports on what node packages are installed.
• --type=pip reports on what Python packages are installed.
• --type=rpm extracts packages from the RPM database.

There are several additional modifiers that define how the output should appear.

While the container-diff analyze command is useful at a relatively high level, container-diff diff features many possible differential analysis capabilities.

Here, the general command takes the following form:

container-diff diff --type=<option> <image1> <image2> <options>

For example, if there is a requirement to look at OS-level changes, the next command creates a report of the OS files found in myimage:2 only:

container-diff diff --type=size --type=apt myimage:1 myimage:2

In its simplest form, this report will look like the following:

-----File-----

These entries have been added to myapp/myimage:1:
    FILE                                                                           SIZE
    /app/node_modules/fsevents                                                     186.2K
	
These entries have been deleted from myapp/myimage:1:
    FILE                                                                           SIZE
    /app/.npm/_cacache/index-v5/ce/9f/58654f1                                      310B
	
These entries have been changed between myapp/myimage:1: and myapp/myimage:2:
    FILE                                                                 SIZE1     SIZE2
    /app/package-lock.json                                               554.6K    554.6K

As with the analyze flag, all the same modifiers provide reports on the differences between two specific containers. Extra modifiers can define the output format of the report and provide a readable format for the target audience.

Admins can codify the commands as templates, which saves time and effort.

Use container-diff to troubleshoot

Another use is to troubleshoot containers, which is rarely an easy task. However, if teams have a new version that doesn't function as desired or intended, but they have a previous version that did work, they can run container-diff with the diff --type=file flag and modifier to identify the problem.

container-diff diff --type=file myimage:1 myimage:2

This creates a report with a list of files in myimage:2 only. This helps admins find which new module is causing any issues. With the file container-diff flag, admins can compare the files further within the two images.

container-diff diff myimage:1 myimage:2 --type=file --filename=<pathtofile>

Finally, use container-diff to preview the effects the new container will have on the environment.

For example, updating the OS in the node image might not produce any negative effects, but it is better that IT admins know ahead of time. To check the changes, this example command moves from Bullseye to Bullseye Slim under Debian 12. This helps teams avoid issues in the operations environment. Here, use the container-diff command like this:

container-diff --type=size --type=apt --type=node node:17-bullseye node:17-bullseye-slim

This container-diff command provides a detailed report of the difference in the resulting container's size, along with which OS and node packages are present. Based on that report, teams can make better-informed decisions on what changes to carry out.

Container-diff is a useful, lightweight tool that requires no special environment to run, which makes it useful for developers and operations staff to keep in their toolbox.

Container-diff is available in a public GitHub repository.