Matchwell™ User Guide

What Matchwell is

Matchwell finds duplicate photos, keeps the best copy of each, and merges what the other copies know into it: their keywords, people, captions, titles, ratings, places and more. The same print scanned twice, a photo saved again as a smaller JPEG, a copy someone emailed back to you, an edited or black and white version: Matchwell groups them and shows you each group before anything changes.

Matchwell comes two ways, with one license for both:

• The Matchwell app, for Windows and Mac. It opens in your web browser and doesn't need Lightroom. It moves the extra copies to a holding folder.
• The Lightroom Classic plug-in: Library > Plug-in Extras > Find duplicate photos. It merges in the catalog and flags the extra copies as rejected.

Nothing is changed until you have checked the groups and clicked Merge, nothing is ever deleted, and every run can be undone.

Quick start

Install Matchwell first: see Install.

In the app

1. Open Matchwell (Start menu on Windows, Applications > ThePictureOrg on a Mac). It opens in your web browser.
2. Click Choose a folder and pick the folder with your photos, then click Find duplicates.
3. Check each group. The KEEP badge marks the copy that stays; click Keep this one under another copy to keep it instead.
4. Click Merge and move. The kept copies get the others' details, and the extra copies move to a Matchwell holding folder.
5. Look them over there and delete the folder yourself when you are sure. Undo this run puts everything back.

In Lightroom Classic

1. Choose Library > Plug-in Extras > Find duplicate photos.
2. Choose where to look (the selected photos, the folders or collections shown now, or the whole catalog) and click Find duplicates.
3. Check the groups, then click Merge.
4. The extra copies are flagged as rejected and put in the collection Matchwell > Duplicates. Nothing is deleted. Library > Plug-in Extras > Undo a Matchwell merge puts everything back.

Next: Clean up duplicates in a folder with the app, Find duplicates in Lightroom Classic, Choose how alike copies must be, Move the kept copy to another folder, Continue a review later.

Clean up duplicates in a folder with the app

Use the app for photos that aren't in Lightroom, or a whole drive of folders. It doesn't need Lightroom.

1. Click Choose a folder, or paste or type a folder's path in the box under it and click Add. Add as many folders as you like. Tick Include the folders inside them for a whole tree. On Windows, the folder dialog has an address bar and a Folder box you can type into. On a Mac, press Cmd-Shift-G in the dialog to type a path.
2. Set How alike and click Find duplicates. A bar shows how far along it is.
3. Check each group. The KEEP badge marks the copy that stays; Keep this one picks another. Each copy shows its size, type and Date taken. Untick These are duplicates (under the group's pictures) to leave a group alone: it moves to the Left out tab when you go to another screen (tick it there to bring it back). When only some copies in a group are duplicates, click Not a duplicate (leave it alone) under each one that isn't: it leaves the group and its file is left alone (never moved or merged), and a second copy marked joins it in a new group of their own at the end (a group left with one copy leaves the review). Matchwell remembers this when you continue the review, even with photos added. Below the pictures, each field shows what the kept copy will get, and each conflict lets you choose. Keywords and people from the other copies are ticked: untick any to leave it off. The With conflicts and Metadata to merge tabs show only those groups. Drag Size to make the pictures bigger. Click a picture to see that copy as large as the window: the left and right arrow keys swap between the copies in its group (same size, same place, so differences stand out), the up and down arrow keys move to the next or previous group, Keep this one keeps the copy shown, Side by side shows them all at once, and Esc closes it. The groups come in one long list to scroll through; a group counts as looked at once you've scrolled to it, and a group you untick leaves the list once it has scrolled out of sight. Click Screens for a windowful at a time instead (One long list switches back): the groups then fill the window, side by side where they fit, with no scrolling, and Next and Previous at the bottom, by Merge and move (or the left and right arrow keys), move to the next or previous screenful.
4. Click Merge and move. The kept copies get the merged metadata, then the other copies move to the holding folder: "Matchwell holding" in the first folder you chose (or one you set under What happens), keeping their folder structure, with a Matchwell report.csv listing every group. Matchwell never looks inside its holding folder when it searches.
5. Look over the holding folder (Open the holding folder), and delete it yourself when you are sure. Changed your mind? Click Undo this run right away, or later choose Menu > Undo an earlier run.

To merge nothing and only move the copies, untick Merge the metadata of the copies under What happens.

Camera raw files are never written to: their merged metadata goes into an .xmp sidecar beside them, as Lightroom and other programs expect.

Find duplicates in Lightroom Classic

Use the plug-in for photos in your Lightroom catalog. It works in the catalog, so the extra copies stay where they are, flagged as rejected, until you delete them.

1. Library > Plug-in Extras > Find duplicate photos.
2. Choose where to look: the selected photos, the folders or collections shown now (with the folders inside them), or the whole catalog. Set How alike and click Find duplicates.
3. Check the groups. They come in long lists to scroll through, up to 50 groups to a list (fewer when the pictures are large); while you look at one list, Matchwell has Lightroom get the next list's pictures ready; Next and Previous move to the next or previous list, and More per list and Fewer per list set how many each holds (25 to 200; fewer opens quicker). Click Screens for a screenful at a time instead: each screen shows as many as fit on your screen, with no scrolling, and One long list switches back. Matchwell remembers your choice. Next and Previous, at the bottom by Merge with the size buttons, move to the next or previous screenful, and your choices on every screen are kept. Each copy is a row of its own: its picture, and beside it its name, the whole path of the folder it is in, its size, type and Date taken (so you can tell which date belongs to which picture), and its buttons. Untick These are duplicates (under the group's copies) to leave a group alone: it leaves the review when you move to another screen (or close), and nothing is changed for it. When only some copies in a group are duplicates, tick Not a duplicate (leave it alone) by each one that isn't: they leave the group when you move on and their files are left alone (never flagged or merged), and two or more ticked together make a new group of their own, at the end (a group left with one copy leaves the review). Matchwell remembers both when you continue the review, even with photos added. Click Keep this one by another copy, untick any keyword or person you don't want on the kept copy, settle each conflict, and pick the Date taken the kept copy gets where the copies differ. Every choice (Date taken, color label, rating, title and the rest) is a row of buttons, each value listed with the copy it comes from. Larger and Smaller change the size of the pictures (the largest is twice the old maximum); a notice shows while the groups are drawn again. Look closer by a picture shows that copy as large as your screen allows, with Previous copy and Next copy to swap between the group's copies in the same place, with no flash, and Keep this one; Back to the groups returns to the review. More per screen and Fewer per screen change how many groups each screen holds, and Matchwell remembers your choice.
4. Click Merge. Merge does the groups you have looked at: if some are still to look at, Matchwell asks whether to merge just the ones looked at (the rest are kept for later: Find duplicate photos offers Continue the review) or all of them. In Lightroom's catalog, each kept copy gets the keywords left ticked and the merged details and the other copies' collections. The other copies are flagged as rejected, get the keyword Matchwell > Duplicate, and are put in the collection Matchwell > Duplicates with the date and time. The kept copies get the keyword Matchwell > Kept copy. These keywords are never exported.
5. Look the extra copies over in that collection. When you are sure, Photo > Delete Rejected Photos removes them from the catalog (Lightroom then asks whether to delete the files from the disk too).

Until you delete them, the copies set aside stay in the catalog, so the next scan leaves out every photo with the keyword Matchwell > Duplicate (the message says how many). It never groups them again with the copy you kept. If you undo the merge, the keyword goes and they are scanned again.

The plug-in works in Lightroom's catalog, so nothing in your files changes, with one exception: Date taken. Lightroom doesn't let plug-ins set it, so when you choose another copy's date, Matchwell has Lightroom save the kept copy's metadata to its file (Metadata > Save Metadata to Files), writes the date into the file (or its .xmp sidecar for camera raw), and has Lightroom read it back (Metadata > Read Metadata from Files). On a Mac, macOS asks once to let Lightroom control the computer (System Settings > Privacy & Security > Accessibility). If Lightroom's menu can't be used, nothing is written and Matchwell lists the dates so you can set them with Metadata > Edit Capture Time.

To put everything back: Library > Plug-in Extras > Undo a Matchwell merge.

Choose how alike copies must be

Under How alike, pick one of five levels. Start at 3 (Lightly edited, the default), which suits most collections:

• Choose 1 or 2 if Matchwell groups photos that aren't copies.
• Choose 4 or 5 if it misses copies you know are there, such as black and white or restored versions. Check level 5's groups closely: photos taken a moment apart can be grouped too.

Deep search also finds mirrored copies and tight crops, and is slower. Each level is described in How alike: the five levels.

Move the kept copy to another folder

After a merge you sometimes want the kept copy somewhere else: in the folder where a duplicate was, or in another folder. Each group has Where the kept copy ends up, in the app and in Lightroom:

• Leave it where it is (the default: nothing moves);
• Move it to the folder of any other copy in the group;
• Another folder: click Choose... (Lightroom) or Another folder... (app) and pick one.

Each group has its own choice, so different groups can go to different folders. If a rejected duplicate in that folder has the same name as the kept copy, the duplicate is renamed "name (2)" (or the next free number) so the kept copy takes its place. Any other file with that name is never touched: the kept copy is then the one named "(2)". A kept copy's .xmp sidecar moves with it.

In Lightroom, a photo can't be moved between folders by a plug-in, so Matchwell does it the way Sortwell does: it moves the file, adds it at its new place with everything the catalog had for it (keywords, ratings, edits, collections and the rest), and removes the old entry. Lightroom says beforehand if a photo has what can't go with it (virtual copies, a stack, Develop snapshots or a published collection). Removing the old entry needs Lightroom Classic 14.3 or later; with an older one it stays as a missing photo, and Library > Synchronize Folder removes it.

Continue a review later

Your review is saved as you go, so a big batch can be spread over several sittings. Close the review part way (or click Merge before you have looked at every group, and choose to merge only the ones you looked at), and the next time you start Matchwell it offers to Continue where you left off, with your choices kept.

• In Lightroom, each catalog has its own saved review: Find duplicate photos asks whether to continue it or start a new scan.
• In the app, each set of folders has its own: the start screen lists them under Continue a review. Forget it removes one (nothing else changes).
• If a photo has changed or gone since the scan, its group is ticked off and marked, so you can check it before merging.
• Photos added since the scan (imported into the same folders, or the catalog when the whole catalog was scanned) are found when you continue. Matchwell says how many and offers to Add them. They are compared with every photo scanned before, and that's quick because only the new ones are read. Your choices stay. A group that gains a copy, or two groups that join into one, are shown again as not looked at, so you can check them, and new groups are added at the end. In Lightroom you can also choose Continue without them.

The review also shows how long the scan took (the scan time), step by step. A deep search over a network drive (a NAS) reads each photo only once and a few at a time, which is much faster on spinning disks.

How alike: the five levels

Choose how alike photos must be under How alike: pick one of the five levels. Start at 3; move toward 1 if Matchwell groups photos that aren't copies, toward 5 if it misses copies you know are there.

Two more choices:

• Also find copies turned sideways or upside down (on by default): a scan saved the wrong way up still matches.
• Deep search (off by default, slower): also finds mirrored copies (a slide scanned from the wrong side) and copies cropped much tighter than the original.
• Under More: Count a camera's RAW + JPEG pair as duplicates. Off by default, so a camera's RAW file and the JPEG it saved beside it (same name, same folder) are left alone.

Matchwell reads each photo small to compare them, using a camera raw file's built-in preview, so it is quick: thousands of photos take a few minutes the first time. What it learns about each photo is remembered, so the next search of the same photos is much faster.

Which copy is kept

In each group Matchwell keeps the best copy:

1. the one with the most pixels;
2. if two are the same size, a camera raw file (or DNG) over a TIFF, a TIFF over a PNG, and those over a HEIC or JPEG;
3. then the larger file, then the older one.

Click Keep this one under another copy (in the app or in Lightroom) to keep it instead.

What is merged

The kept copy gets, from the other copies in its group:

• the keywords and people of the others (each one is listed with a tick: untick any you don't want on the kept copy);
• each field it doesn't have: title, caption, headline, rating, color label, GPS location, sublocation, city, state, country, creator, copyright date taken (when the copies differ, you choose which date the kept copy gets); the app also merges people's face areas;
• the other copies' collections (Lightroom).

When two copies disagree, for example two different captions, Matchwell shows both and you choose:

• the kept copy's (the default: nothing changes unless you choose);
• another copy's value;
• combine them: texts are joined (a caption with a blank line between), the rating is the highest, and the date is the earliest. In the app you can edit the combined text before merging.

Combine all conflicts and Keep the kept copy's values (app) set every group at once.

Undo

Every run keeps an undo file in your PictureOrg folder ("Matchwell-undo"). In the app, undo moves every copy back to where it was (a kept copy you moved goes back to its old folder too) and puts back the kept copy's old metadata (any sidecar Matchwell made is removed). In Lightroom, undo first moves back any kept copy you moved (and gives a renamed duplicate its name back), then puts back the kept copies' old fields, keywords, collections and Date taken, unflags the other copies and removes the run's collection. Runs made in the app are undone in the app, and runs made in Lightroom in Lightroom.

Install

There are three downloads. The installers ask what to install: the Lightroom Classic plug-in, the standalone app (no Lightroom needed), or both. One license covers both, and you can run the installer again later to add the other.

Windows: the Setup program (ThePictureOrg-Matchwell-Setup-<version>.exe)

1. If you are installing the plug-in, close Lightroom Classic.
2. Double-click the Setup program. If Windows shows "Windows protected your PC", click More info, then Run anyway.
3. Accept the license, tick what to install and click Install.
4. The app is in the Start menu as Matchwell. For the plug-in, start Lightroom Classic. Then choose Library > Plug-in Extras > Find duplicate photos.

Mac: the Install Matchwell app (ThePictureOrg-Matchwell-Mac-<version>.zip)

1. Double-click the zip to unzip it. If you are installing the plug-in, quit Lightroom Classic.
2. Double-click Install Matchwell, and click Open when macOS asks. It is signed and checked by Apple.
3. Choose what to install and click Install.
4. The app is in Applications > ThePictureOrg. For the plug-in, start Lightroom Classic. Then choose Library > Plug-in Extras > Find duplicate photos.

On a Mac with an Intel processor, Matchwell uses the Mac's own Python 3 with its picture packages. If they are missing, the installer says so: install Python 3 from python.org, then run pip3 install numpy opencv-python-headless pillow rawpy in Terminal.

Updating and removing: run the installer from the new download the same way, or click Install now when Matchwell offers an update (see Updates). Your settings and license key are kept. To remove Matchwell, use Uninstall Matchwell in the Start menu on Windows, or the Uninstall Matchwell app in the Mac download.

Installing the plug-in by hand: on Windows, right-click ThePictureOrg-Matchwell-Win-<version>.zip, choose Properties, tick Unblock, and unzip it. On a Mac, right-click Install Matchwell, choose Show Package Contents and open Contents > Resources. Move the PictureOrgMatchwell.lrplugin folder somewhere permanent, then in Lightroom Classic choose File > Plug-in Manager > Add and pick it. Use one way or the other, not both, or the menu appears twice.

Where it goes: the installers put the plug-in in Lightroom's own plug-in folder for your user account, where Lightroom finds it by itself (%APPDATA%\Adobe\Lightroom\Modules\PictureOrgMatchwell.lrplugin on Windows, ~/Library/Application Support/Adobe/Lightroom/Modules/PictureOrgMatchwell.lrplugin on a Mac). No administrator password is needed. If the Mac installer has a problem, it keeps a log for support in ~/Library/Logs/PictureOrg/Matchwell-install.log.

License and free trial

• Free trial: every feature works for 21 days on each computer. The Plug-in Manager panel and the app show how many days are left, for example "Free trial: 14 days left".
• After the trial: for 7 more days Matchwell still works, with a reminder. After that, finding duplicates still works, and merging needs a license key. When a license key is needed, Matchwell says "the free trial has ended" and offers Buy a license and Enter key....
• Buying: click Buy a license in the License section of File > Plug-in Manager (select Matchwell), or on the license line at the top of the app, or go to thepictureorg.com/tools. One license is for one person on up to 2 computers, covers the app and the Lightroom plug-in, and includes complimentary updates within the major version (a version 1 key works for every 1.x release).
• Entering your key: paste the whole key from your order email into the License key box in the Plug-in Manager and click Enter key, or click the license line at the top of the app. Spaces and line breaks don't matter. It then says "Licensed to" and your name. The key is checked on this computer: nothing is sent anywhere, and no internet connection is needed.
• Plug-in and app: one license, one free trial. The plug-in and the app share the key and the 21-day count on each computer, so a key entered in either unlocks both.
• New computer: click Remove license from this computer on the old one (it asks first), then enter the key on the new one.
• Where the key is kept: in your user account, not in the program's folder, so it stays through updates and reinstalling: %LOCALAPPDATA%\PictureOrg on Windows, ~/Library/Application Support/PictureOrg on a Mac.

Updates

• Automatic check: once a day Matchwell looks up the current version number on thepictureorg.com's download service, in the background when Lightroom starts and when you run it. Only that small version list is fetched: nothing about your computer, your photos or your license key is sent.
• When a new version is out: the next time you run Matchwell, a message says so once per Lightroom session: Install now (or Download), Not now (asks again next time you start Lightroom) and Skip this version (stays quiet until a later version comes out). Nothing is downloaded or installed until you click.
• Install now: Matchwell downloads the update, checks that it arrived whole and unchanged, that it carries The Picture Org's release signature and that it is newer than the version you have, and installs it into its own folder, with a progress bar. Then quit and restart Lightroom Classic to start using it. If anything goes wrong, every file is put back as it was.
• Download: opens the installer download in your browser; close Lightroom Classic and run the new Setup program (Windows) or Install Matchwell (Mac). Your settings and license key are kept either way.
• Plug-in Manager > Updates: shows your version and whether a newer one is out, with Check now, Install update, Download installer and What's new. Untick Check for updates automatically to turn the daily check off; Check now still works. When an update can't be installed from inside your version, the panel says to use Download installer for that one.
• The app checks once a day when it opens, and Check for updates checks at any time. When a new version is out, a bar lets you install it (the app installs it into its own folder, then restarts itself), download the installer, or see what's new. The plug-in and the app update separately: each installed copy has its own files.

Updates within the major version are complimentary.

Help

• Check my setup (in the app's menu, or in File > Plug-in Manager with Matchwell selected) checks that everything Matchwell needs works on this computer, and shows the result as text you can copy or save.
• Create an error log (in the app's menu, or Library > Plug-in Extras > Matchwell: Create an error log) saves a text file on your Desktop with what Matchwell did. Email it to The Picture Org with a few words about what went wrong. File names are in it; your photos aren't, and nothing is sent by itself.

Appendix: What's new

0.9.23 (25 October 2026)

• Each group can move its kept copy after the merge, to the folder of one of its duplicates or to another folder. A rejected duplicate there with the same name is renamed "name (2)".
• Lightroom: the list's previews are fetched in the background, and a line under the list explains what Merge does.

0.9.21 (25 October 2026)

• Lightroom: each copy is a row of its own, with the whole path of its folder. A notice shows while the groups are drawn again, and every group in a long list draws.

0.9.19 (25 October 2026)

• Lightroom: the groups come in lists of 50 (25 to 200), each copy shows its folder, and opening a saved review shows its progress.

Earlier versions: see CHANGELOG.txt.

Appendix: License and credits

© 2026 The Picture Org LLC · thepictureorg.com. Matchwell uses ExifTool by Phil Harvey to read and write metadata, OpenCV and NumPy to compare pictures, and LibRaw (rawpy) to read camera raw previews. See NOTICE.txt.