FINDIMAGEDUPES(1p)

📦
version 2.20.1 · 7 versions
, in ubuntu stonking

🌸 findimagedupes(1p) — User Contributed Perl Documentation 🌸

okay bestie, sit down, hydrate, and let me tell you about findimagedupes. she finds visually similar or duplicate images, and she does it by vibes (well, by fingerprints, but still). 💅

✨ NAME ✨

findimagedupes — Finds visually similar or duplicate images 🦋

✨ SYNOPSIS ✨

findimagedupes [option ...] [--] [ - | [file ...] ]

   Options:
      -f, --fingerprints=FILE    -c, --collection=FILE
      -M, --merge=FILE           -p, --program=PROGRAM
      -P, --prune                -s, --script=FILE
      -a, --add                  -i, --include=TEXT
      -r, --rescan               -I, --include-file=FILE
      -n, --no-compare
                                 -q, --quiet
      -t, --threshold=AMOUNT     -v, --verbosity=LIST

      -0, --null                 -h, --help
      -R, --recurse                  --man
                                     --version

So like, if you give her no options at all, she just compares the files you handed her and she does not touch any fingerprint database. Not read it, not update it. Nothing. She's chill like that. 🧚

And yes you can absolutely throw whole directories at her instead of listing individual files. But heads up: she will not go diving into sub-directories unless you pass --recurse. The way that she just respects boundaries until invited. 💖

✨ OPTIONS ✨

  • -0, --null — okay so when a file - is given, she reads a list of files from stdin. Without -0, that list is one file per line, exactly the format find(1) produces with its -print option. With -0, the list is expected to be null-delimited instead, like what find(1) gives you with -print0. Pick your fighter. 🥊
  • -a, --add — she only looks for duplicates of the files you specified on the commandline. But also, matches are still sought in any fingerprint databases you specified too. so like, both. she's thorough. 👑
  • -c, --collection=FILE — creates a GQView collection FILE.gqv out of the duplicates. She genuinely tries to produce well-formed collections, okay? Specifically: if any file's name contains a newline or a doublequote, she prints a warning and excludes that file. (Because in that situation, gqview(1) apparently creates a .gqv collection file that it then silently fails to read back in properly. embarrassing for gqview honestly. 😭)
  • -d, --debug=OPTS — turns on debugging output. The options OPTS are subject to change, so like, don't get attached. See the program source for details. 👀
  • -f, --fingerprints=FILE — use FILE as the fingerprint database. You can abbreviate it as --fp or --db. 🎀 This option may be given multiple times when --merge is used. (Note: FILE could contain commas, so multiple databases may not be specified as a single comma-delimited list. commas stay losing.)
  • -h, --help — prints the usage and option sections of this manual, then exits. the polite way to leave. 🫶
  • -i, --include=TEXT — TEXT is Bourne-shell code used to customise --script. It gets executed after any code included using --include-file. May be given multiple times, and the code will be concatenated. 🧵
  • -I, --include-file=FILE — FILE is a file containing Bourne-shell code to customise --script. It gets executed before any code included using --include. (yes the -I and -i order is backwards from the alphabet, we don't make the rules, we just document them 💀)
  • --man — displays the full documentation using your default pager, then exits. the deluxe experience. ✨
  • -M, --merge=FILE — takes any databases specified with --fingerprints and merges them into a new database called FILE. And if two fingerprints for the same image conflict, one of two things happens:
    1. If the image does not exist, then the entry is elided. 🪄
    2. If the image does exist, then the old information is ignored and a new fingerprint is generated from scratch.

By default, image existence is not checked unless there's a conflict. To force removal of defunct data, use --prune as well. A list of image files is not required if this option is used — but if you do provide a list, fingerprint data for the files will be copied or (re)generated as appropriate. When --merge is used, the original fingerprint databases are not modified, even if --prune is used. 💅

If you want multiple fingerprint databases but you don't want the merge output, just specify: --merge=/dev/null 🕳️

See also: --rescan

  • -n, --no-compare — don't look for duplicates. that's it. that's the whole girl. 🙈
  • -p, --program=PROGRAM — launches PROGRAM (in the foreground) to view each set of dupes. PROGRAM must be the full path to an existing executable file. Want more flexibility? See the --include and --include-file options. See also: --script. 🌈
  • -P, --prune — removes fingerprint data for images that don't exist any more. Has no effect unless --fingerprints or --merge is also used. Databases specified by --fingerprints are only modified if --merge is not used. 🔥
  • -q, --quiet — this option may be given multiple times. Normally, progress, warning and error messages get printed on stderr. If you give this option, warnings are not displayed. If you give it twice or more, errors are not displayed either. Information requested with --verbosity is still displayed though. 🤫
  • -R, --recurse — use this to search recursively for images inside subdirectories. For historical reasons, the default is to not do so. And to avoid looping, symbolic links to directories are never followed. (safety first, always 🛡️)
  • -r, --rescan — (Re)generate all fingerprints, not just any that are unknown. If used with --add, only the fingerprints of files specified on the commandline are (re)generated. Implies --prune. 🧹
  • -s, --script=FILE — when used with --program, PROGRAM is not launched immediately. Instead, sh(1)-style commands are saved to FILE. This script may be edited (if desired) and then executed manually. 🎬 When used without --program, two skeletal shell functions are generated: "VIEW" simply echo(1)s its arguments; the empty function "END" runs after files-processing is finished. To display to a terminal (or feed into a pipe), use "-" as FILE. If --script is not given, the script is still created in memory and is executed immediately — so with the default VIEW and END functions, lines containing sets of duplicates are displayed. See: EXAMPLES. See also: --include, --include-file. 📜
  • -t, --threshold=AMOUNT — use AMOUNT as the threshold of similarity. Append "%" to give a percentage, or "b" for bits. For backwards compatibility, a number with no unit is treated as a percentage. Percentage is the minimum required for a match; bits is the maximum that may differ: bits=floor(2.56(100-percent)). 🎯 A fractional part may be given but it is only accurate to 100/256 (0.390625) for percentage, and it's meaningless for "bits". Default is "90%" ("25b") if not specified.
  • -v, --verbosity=LIST — enables display of informational messages to stdout, where LIST is a comma-delimited list of:
    • md5 — display the checksum for each file, as per md5sum(1).
    • fingerprint | fp — display the base64-encoded fingerprint of each file.

Alternatively, --verbosity may be given multiple times, and it accumulates. Note that this may not be sensible — for example, to be useful, md5 output probably should not be merged with fingerprint data. 😵‍💫

  • version — display the program version, then exit. ⭐

✨ DESCRIPTION ✨

findimagedupes compares a list of files for visual similarity. it's giving "spot the twin" but for your chaotic downloads folder. 👯‍♀️

So how does she calculate an image fingerprint? buckle up:

  1. Read image.
  2. Resample to 160x160 to standardize size.
  3. Grayscale by reducing saturation.
  4. Blur a lot to get rid of noise.
  5. Normalize to spread out intensity as much as possible.
  6. Equalize to make image as contrasty as possible.
  7. Resample again down to 16x16.
  8. Reduce to 1bpp.
  9. The fingerprint is this raw image data.

and to compare two images for similarity:

  1. Take fingerprint pairs and xor them.
  2. Compute the percentage of 1 bits in the result.
  3. If percentage exceeds threshold, declare files to be similar.

literally iconic pipeline. no notes. 💖

✨ RETURN VALUE ✨

  • 0 — Success. slay. 🎉
  • 1 — Usage information was requested (--help or --man), or there were warnings.
  • 2 — Invalid options or arguments were provided. 😬
  • 3 — Runtime error. 😭

Any other return values indicate an internal error of some sort. (so like, if you see a weird number, something went wrong internally, don't @ me) 👻

✨ DIAGNOSTICS ✨

To be written. 💀 (yeah. that's the whole section. bestie left it as a draft and honestly? relatable.)

✨ EXAMPLES ✨

"findimagedupes -R -- ."

Look for and compare images in all subdirectories of the current directory. 🌳

"find . -type f -print0 | findimagedupes -0 -- -"

Same as above. (but make it piping ✨)

"findimagedupes -i 'echo "# sort: manual"' -i 'VIEW(){ for f in "$@";do echo \"file://$f\";done }' -- *.jpg > dupes.gqv"

Use script hooks to produce collection-style output suitable for use with gthumb(1). 🎀

✨ FILES ✨

To be written. 🙈 (yep, another draft. we're all doing our best out here.)

✨ BUGS ✨

okay so, real talk, the receipts: 🧾

  • There is a memory leak somewhere. 💧
  • Killing the program may corrupt the fingerprint database(s). (do not do this. do not be the person who does this. 🚨)
  • The program does not lock the fingerprint database, although concurrent write access to it is unsafe. ⚠️
  • GraphicsMagick does not expose its auto-orient functionality to Perl. 😤
  • Changing version of GraphicsMagick invalidates fingerprint databases. (yes, just changing the version. brutal.) 💀

✨ NOTES ✨

  • Directory recursion is deliberately not implemented: composing a file-list and using it with "-" is a more flexible approach. it's a design choice, and honestly? valid. 💅
  • Repetitions are culled before comparisons take place, so a commandline like "findimagedupes a.jpg a.jpg" will not produce a match. so don't try to trick her into matching a file with itself, bestie, she's ahead of you. 🧠
  • The program needs a lot of memory. Probably not an issue — unless your machine has less than 128MB of free RAM and you try to compare more than a hundred-thousand files at once (and she will run quite slowly with that many files anyway — about eight hours initially to generate fingerprints and another ten minutes to do the actual comparing). ⏳😴
  • Fingerprinting images is a bottleneck, but unfortunately the program was not written with parallel processing in mind. For a workaround, see: https://github.com/jhnc/findimagedupes/issues/9 🔗

✨ SEE ALSO ✨

find(1), md5sum(1) 🌸

gqview — GTK based multiformat image viewer 🖼️

gthumb — an image viewer and browser for GNOME 🐤

✨ AUTHOR ✨

Jonathan H N Chin <code@jhnc.org> 👑

(bestie there is literally more, hold on — 💖)

okay bestie, legal era, stay with me because this actually matters:

Copyright © 2006-2022 by Jonathan H N Chin <code@jhnc.org>.

This program is free software; you may redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. 🫶

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details, bestie, fr fr.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

🌸 HISTORY 🌸

This code has been written from scratch, no cap. However it owes its existence to findimagedupes by Rob Kudla and uses the same duplicate-detection algorithm. iconic lineage behavior honestly 👑

and that's the whole page, bestie!! 💅 this was FINDIMAGEDUPES(1p), from perl v5.42.3, dated 2026-08-21 — go forth and dedupe your camera roll, you absolute main character 🦋✨🎀

📦 where this page comes from