Skip to content

Compare two given screenshots and return similarity as percentage


Notifications You must be signed in to change notification settings



Folders and files

Last commit message
Last commit date

Latest commit



43 Commits

Repository files navigation


Latest version GoDoc Used LICENSE travis test result Go Report Card


grml solutions



gonamespace (API)

scmp ""

gonamespace (CLI)

What is it about?

You can compare two image files and it will show a difference score between 0 and 1. Using transparent reference PNG images, you can also skip certain areas of the file. Unlike the title, you can compare arbitrary images, but our usecase is screenshot comparison.

You can either get the binary executable or use this implementation as a go dependency.

Why should I use it?

We take screenshots of running live systems and want to know, whether they are (visually) in a certain state.

Who should use it?

Especially software developers testing software might find this software useful. Consider that modern browsers feature headless modes (e.g. Mozilla Firefox, Google Chrome). With this feature it will be easy to take screenshots of websites and this project enables you to compare them. Thus, web developers might find it useful as well. We use it in combination with virtualization software.

How to install

You can run go get:

go get

and start developing! 😊 You can build the executable using:

go build

How to run

  1. Go to

  2. Click on the Releases link github releases

  3. Scroll down, choose the download appropriate for your platform Downloads

  4. Once the download has finished, extract the files of the tar-gz archive

  5. Run the file screenshot-compare on the Terminal (cmd.exe or PowerShell for Windows users) Terminal

One terminal example is the comparison of grml_booting_totalmemory_kB.png and grml_booting_totalmemory_MB.png:

$ ./screenshot-compare tests/grml_booting_totalmemory_kB.png tests/grml_booting_totalmemory_MB.png
runtime:                372.624129ms
timeout:                false
pixels different:       168
difference percentage:  0.017 %

The exit code also shows the difference percentage. Run screenshot-compare without arguments to see the usage description for this.

How to call

You can call the main routine Compare programmatically. Either you look into the cli/ or tests/ directories for examples or take a look at this example:

package main

import (

    scmp ""

func main() {
    config := scmp.NewConfig()
    result := scmp.Result{}

    // prepare images for comparison
    err := config.BaseImg.FromFilepath("image1.png")
    if err != nil {
    err = config.RefImg.FromFilepath("image2.png")
    if err != nil {

    // run comparison
    err = scmp.Compare(config, &result)
    if err != nil {

    // show score

As you can see, I bound the v1 API import to the alias scmp which is best practice.

Understanding the score

  • If the dimensions of the two images do not correspond, we reject.

  • We look at every individual pixel and determine a difference value between 0 and 1 based on the color.

  • We multiply the difference value by the alpha channel value of the reference image.

  • We evaluate the average over all pixels of the image. This is our image difference score.

White and black provides the hugest difference (though 100% is not limited to black/white):

score 100% for white/black and score 59.7% for black/blue

These randimg images use similar colors, but the structures are slightly (left) or vastly (right) translated.

score 37.25% for two similar images where structures are slightly translated and score 43.97% for similar structures but vastly translated

If you use the Y'UV color space, the score slightly changes (RGB provided 59.7% for black/blue):

Y’UV score 100% for white/black and Y’UV score 30.51% for black/blue

This image illustrates the transparency feature:

difference 0% illustrating that areas with transparency in the reference areas are skipped

PNG and JPEG file formats can be processed. If you want a binary classifier whether the images are similar, 0.1 (i.e. 10%) might be a suitable classifier.

Source Code

The source code is available at Github.


See the LICENSE file (Hint: MIT license).



first release: PNG only, transparency support


goroutine support, timeout argument, slight performance improvement


complete rewrite, --wait and --timeout parameters, Y'UV support


improved README with illustrations


introduce README section "How to run"


complete rewrite of the core with same functionality
allows to retrieve config from env vars, JSON file and CLI args
result shows the number of pixels with differences
public API / implementation as a library
source code was moved into v1 module to allow usage in a backwards-compatible way


switch from meisterluk to GrmlForensic namespace
add goreleaser configuration file


Please report any issues on the Github issues page.


Compare two given screenshots and return similarity as percentage









  • Go 100.0%