Skip to main content

Present two images side-by-side for visual comparison

Project description


A command-line tool that combines two pictures into a single, larger one, and opens a GUI window (provided by the Python Imaging Library) or an external image viewer.

You could use it with a version control tool, e.g.

bzr diff *.png --using=imgdiff


bzr diff *.png --using='imgdiff --eog -H'


pip install imgdiff or download it from PyPI.


Run imgdiff --help to see this help message:

Usage: imgdiff [options] image1 image2

Compare two images side-by-side

  -h, --help            show this help message and exit
  -o OUTFILE            write the combined image to a file
  --viewer=COMMAND      use an external image viewer (default: builtin)
  --eog                 use Eye of Gnome (same as --viewer eog)
  --grace=SECONDS       seconds to wait before removing temporary file when
                        using an external viewer (default: 1.0)
  -H, --highlight       highlight differences (EXPERIMENTAL)
  -S, --smart-highlight
                        highlight differences in a smarter way (EXPERIMENTAL)
  --opacity=OPACITY     minimum opacity for highlighting (default 64)
  --timeout=TIMEOUT     skip highlighting if it takes too long (default: 10
  --auto                pick orientation automatically (default)
  --lr, --left-right    force orientation to left-and-right
  --tb, --top-bottom    force orientation to top-and-bottom
  --bgcolor=RGB         background color (default: fff)
  --sepcolor=RGB        separator line color (default: ccc)
  --spacing=N           spacing between images (default: 3 pixels)
  --border=N            border around images (default: 0 pixels)

Output Examples

First example:

imgdiff set1/42.png set3/
example #1

Here the images are wide and short, so imgdiff decided to put them one above the other.

Same example, with highlighting enabled:

imgdiff set1/42.png set3/ -H
example #2

You can see that it doesn’t work very well, although it can produce nice results in simpler cases:

imgdiff set1/42.png set2/ -H
example #3

Support and Development

The source code can be found in this Git repository:

To check it out, use git clone

Report bugs at


1.7.1 (2019-04-23)

  • Claim Python 3.6 and 3.7 support (no code changes required).

  • Drop Python 3.3 and 3.4 support.

1.7.0 (2016-09-17)

  • Clarify the help message for the --opacity option.

  • Add Python 3.5 support.

  • Drop Python 2.6 and 3.2 support.

1.6.0 (2014-12-01)

  • Add Python 3 support.

  • Make the –timeout option actually work.

  • Drop the –selftest option. Add a real test suite with 100% coverage (which actually means little, since these are smoke tests that don’t inspect the results for correctness.)

1.5.0 (2013-08-11)

  • Suppress progress output if stderr is not a terminal.

  • Make it possible to abort –highligh/–smart-highlight logic by pressing ^C.

  • Abort –highlight/–smart-highlight logic if it takes longer than 10 seconds (timeout changeable with –timeout; use 0 to turn it off).

1.4.1 (2013-08-09)

  • Depend on Pillow instead of PIL.

  • Moved to GitHub.

1.4.0 (2010-12-19)

  • Accepts directory names: imgdiff dir1/img.png dir2/.

  • Centers images relative to each other if they have different width/height.

  • Automatic orientation (–auto) uses the golden ratio (1:1.618) as its goal for desired height:width instead of a 1:1 square.

  • New experimental options: –highlight (-H) and –smart-highlight (-S). These highlight areas that are different and fade out areas that are similar. Or at least they try.

  • New options for tweaking the output: –bgcolor, –sepcolor, –spacing, –border, –opacity.

  • New option: –eog as alias for –viewer eog, but shorter. Guess what desktop environment I’m using. ;-)

  • A puny “test suite”, runnable with imgdiff –selftest.

  • Better source code documentation via docstrings.

1.3.0 (2010-12-18)

  • First public release. Options supported: -o, –viewer, –grace, –auto, –lr, –tb, –help.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

imgdiff-1.7.1.tar.gz (1.4 MB view hashes)

Uploaded Source

Built Distribution

imgdiff-1.7.1-py2.py3-none-any.whl (10.3 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page