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.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.

Filename, size & hash SHA256 hash help File type Python version Upload date
imgdiff-1.7.0-py2-none-any.whl (12.4 kB) Copy SHA256 hash SHA256 Wheel py2
imgdiff-1.7.0.tar.gz (1.3 MB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page