Skip to main content

​
Installation

Get started with imghash in your Go project with a single command.

​
Requirements

imghash requires Go 1.25 or later. Check your version with go version.
The library has minimal dependencies:
  • golang.org/x/image - Extended image format support

​
Install with go get

1

Install the package

Run the following command in your project directory:
go get -u github.com/ajdnik/imghash/v2
This downloads the latest version of imghash v2 and adds it to your go.mod file.
2

Import the package

Add the import to your Go source files:
import "github.com/ajdnik/imghash/v2"
Most consumers only need the top-level imghash package. Core types (Hash, Binary, UInt8, Float64, Distance) are re-exported there.
3

Verify installation

Create a simple test file to verify the installation:
test.go
package main

import (
    "fmt"
    "github.com/ajdnik/imghash/v2"
)

func main() {
    pdq, err := imghash.NewPDQ()
    if err != nil {
        panic(err)
    }
    fmt.Printf("PDQ hasher created successfully: %T\n", pdq)
}
Run it:
go run test.go
You should see:
PDQ hasher created successfully: imghash.PDQ

​
Package Structure

imghash is organized into several packages:

​
Top-Level Package

The main imghash package exports all algorithms and core types: 
import "github.com/ajdnik/imghash/v2"

// All 18 hash algorithms
pdq, _ := imghash.NewPDQ()
avg, _ := imghash.NewAverage()
phash, _ := imghash.NewPHash()
// ... and more

// Re-exported core types
var h imghash.Hash      // Common hash interface
var b imghash.Binary    // Bit-level hash
var u imghash.UInt8     // Byte-level hash
var f imghash.Float64   // Float-level hash
var d imghash.Distance  // Distance measure

​
Subpackages (Advanced Usage)

For advanced use cases, you can import specific subpackages: 
import (
    "github.com/ajdnik/imghash/v2"
    "github.com/ajdnik/imghash/v2/hashtype"    // Hash type implementations
    "github.com/ajdnik/imghash/v2/similarity"  // Distance functions
)

// Use distance functions directly
dist, _ := similarity.Hamming(hash1, hash2)
dist, _ = similarity.L2(hash1, hash2)
dist, _ = similarity.Cosine(hash1, hash2)

// Create hash types manually
binary := hashtype.NewBinary(256) // 256-bit hash
Most users won’t need to import subpackages. The main imghash package re-exports everything you need.

​
Supported Image Formats

imghash automatically registers decoders for common image formats:
  • JPEG - .jpg, .jpeg
  • PNG - .png
  • GIF - .gif
These are registered via standard library imports:
imghash/convenience.go:5-7
import (
    _ "image/gif"  // register GIF decoder
    _ "image/jpeg" // register JPEG decoder
    _ "image/png"  // register PNG decoder
)

​
Adding More Formats

To support additional formats like WebP or TIFF, import their decoders: 
import (
    "github.com/ajdnik/imghash/v2"
    _ "golang.org/x/image/webp"  // WebP support
    _ "golang.org/x/image/tiff"  // TIFF support
)

​
Module Configuration

Your go.mod file should include: 
module your-project

go 1.25

require github.com/ajdnik/imghash/v2 v2.x.x
The indirect dependency on golang.org/x/image will be added automatically: 
require (
    github.com/ajdnik/imghash/v2 v2.x.x
    golang.org/x/image v0.36.0 // indirect
)

​
Version Pinning

To use a specific version: 
go get github.com/ajdnik/imghash/[email protected]
To update to the latest version: 
go get -u github.com/ajdnik/imghash/v2
go mod tidy

​
Troubleshooting

This means the package isn’t downloaded. Run:
go mod download
go mod tidy
Make sure you’re using /v2 in the import path for version 2:
import "github.com/ajdnik/imghash/v2"  // Correct
import "github.com/ajdnik/imghash"     // Wrong - this is v1
The image format isn’t registered. Add the appropriate decoder import:
import _ "golang.org/x/image/webp"
imghash v2 requires Go 1.25+. Upgrade Go or use an older version of imghash:
go get github.com/ajdnik/[email protected]

​
Next Steps

Now that you have imghash installed, proceed to the Quick Start Guide to compute your first perceptual hash.

Build docs developers (and LLMs) love

Get started for freeTalk to us