It seems that Recoll will sometimes find data that Spotlight misses (especially inside pdfs apparently, which is probably more to the credit of poppler than recoll itself).

There several possible ways to install Recoll in MacOS:

  • Use MacPorts: there is a Recoll port in MacPorts. It is currently (2022-03) quite up to date. There is also a quite simple way to build a more recent version through a local ports tree (see further down).

  • Use Homebrew: there is a Homebrew recipee in the recoll source repository, and one on github.

  • Probably best: use a hybrid approach: install Recoll through a standalone native Mac package (a .app in a dmg, downloaded from the Recoll Web site), and add the required helper applications (e.g. poppler for PDF) with your preferred method (MacPorts, Homebrew, Fink, etc.).

The MacPorts and Homebrew versions of Recoll have been irregularly updated in the past. The helper applications are more actively maintained in most cases, because they are more commonly used or easier to build (or both).

If you are not a regular MacPorts or Homebrew user, I do think that the third, hybrid, approach is the easiest, moreso in periods where the Recoll port is not recent.

In all cases: if you run indexing before installing the needed helpers (which makes sense as this will give you a list of possibly missing ones from the "Help→Missing Helpers" menu), you will need to either reset the index or run a "File→Special Indexing" pass with the "Retry previously failed files" option checked (no need for anything else), after installing the missing helpers. By default, a Recoll incremental indexing pass does not retry files which could not previously be indexed.

Hybrid approach

You will install the Recoll DMG just like any regular Mac OS application:

Recoll 1.38.1 built on Big Sur, Universal Binary and Qt 6, should run on both Intel x86 and Apple arm64: recoll-1.38.1-20240516-375bcbc0.dmg

This version now includes a copy of the poppler tools, so it should be able to index PDF files "out of the box", unlike previous versions which required a separate poppler installation.

Should also run on Apple Silicon, but I have not tried because I don’t have the right Mac. Some feedback on the matter would be great ! See for older versions at the end of this section.

I don’t sign the application, as I don’t relish paying Apple 99 dollars per year just for this. If the unsigned binary is a problem for you (which I do understand), you can also build the bundle yourself. Also, the .dmg has checksum and pgp signature companion files, as described here.

Here is a tentative recipee to build the bundle. There may be a few rough edges yet, please contact me if you run into trouble.


The ARM-based Mac computers will absolutely refuse to run unsigned code (unlike the Intel Macs which protest but yield to user insistence). I can’t sign the Recoll bundle, but happily enough, it appears that you can do it yourself with the following commands (the second one gets rid of the helpful proposition to move the app to the Trash):

codesign -s - -f --deep /path/to/recoll.app
xattr -rd com.apple.quarantine /path/to/recoll.app

Thanks to Recoll user Che Kon for finding this out.

The base Recoll.app installation processes the "internal" Recoll document formats (text, html, libreoffice, ms-office, mail, epub, etc.). I only tested it on x86 (see above).

It would be difficult and a lot of work to get all helper applications to live inside Recoll.app, as most need a modification to learn where to find their data files. For example, versions before 1.38.0 could not process PDF files, for which you will need to install 'poppler'. The PDF situation changed in 1.38.0, but you may have file types which are still not processed by the default installation.

So you will need to install the needed helpers with your preferred method (MacPorts, Homebrew etc.). Don’t forget: see note above: you need to reset the index or run a special indexing after installing new helpers.

Recoll then needs a little help to find the commands, because the PATH variable seen when started through the desktop launcher is quite restricted. There is a configuration variable for this: recollhelperpath, to be set in your index configuration file (~/.recoll/recoll.conf by default).

Typically, if you are using MacPorts to install the helpers:

recollhelperpath = /opt/local/bin

With 'classical' Homebrew this would probably be:

recollhelperpath = /usr/local/bin

Newer Homebrew installs, esp. on M1 use /opt/homebrew/bin:

recollhelperpath = /opt/homebrew/bin

You can include several directories by separating the paths with colons:

recollhelperpath = /opt/local/bin:/usr/local/bin:/Users/me/bin

Older "hybrid approach" versions

Recoll 1.37.4 built on Big Sur, Universal Binary and Qt 6, should run on both Intel x86 and Apple arm64: recoll-1.37.4-20240319-626644dc.dmg

Recoll 1.33.4 built on Big Sur, Universal Binary and Qt 6, should run on both Intel x86 and Apple arm64: recoll-1.33.4-20230107-097c8ea8.dmg

Recoll 1.32.1 built on Big Sur, Universal Binary and Qt 6, should run on both Intel x86 and Apple arm64: recoll-1.32.1-20220516-e34ccb69.dmg

Recoll 1.32 built on Big Sur, Qt 5: recoll-1.32.0-20220311-63d1318d.dmg

Recoll 1.31 built on Big Sur, Qt 5: recoll-1.31.5-20220104-07867573.dmg

Recoll with MacPorts

The official MacPorts version is usually a bit old as it’s not easy to get it to update. However, the current version (03-2022) is 1.31.6, which is quite recent.

Standard MacPorts install:

link:https://www.MacPorts.org/install.php[Install MacPorts].
Then type "sudo port install recoll"

Recoll is then available from the command line and as an icon in the usual MacPorts applications place.

You can also easily perform a local repository build if the Portfile from the recoll source tree is more recent. Look at the recipe, it’s really quite simple.