Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

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/

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

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

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

Release History

This version
History Node


History Node


History Node


History Node


History Node


History Node


Download Files

Download Files

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

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
imgdiff-1.7.0-py2-none-any.whl (12.4 kB) Copy SHA256 Checksum SHA256 py2 Wheel Sep 17, 2016
imgdiff-1.7.0.tar.gz (1.3 MB) Copy SHA256 Checksum SHA256 Source Sep 17, 2016

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting