Overview

There several possible ways to install Recoll in MacOS:

  • Use MacPorts: there is a Recoll port in MacPorts. It is currently (2024-08) a bit outdated (1.31) but quite usable. There is also a quite simple way to build a more recent version through a local ports tree (see further down).

  • Use Homebrew: a kind developper maintains a Homebrew Recoll Formula on github. This is actually just a cask which pulls a version of the Recoll bundle/dmg described below. Alternatively, it has also recently (recoll 1.41) become possible to run the regular Recoll build using packages from Homebrew, see below. This is probably the best approach if you need the Python extension.

  • Use a hybrid approach: install Recoll as a native Mac app downloaded from the Recoll Web site, and add the required helper applications with your preferred method (MacPorts, Homebrew, Fink, etc.). This will get you a native Recoll.app bundle to be installed in, e.g., /Applications. You can also build the bundle yourself.

Note
 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.

Recoll meson build with Homebrew packages

The Recoll meson/ninja build has been fixed in version 1.41 to work with homebrew packages. Recipee:

  • Install the appropriate homebrew packages:

    brew install meson pkgconf xapian libxml2 libmagic chmlib aspell

  • Extract the recoll tree, either from the git repository or from a tar archive.

  • If the tree comes from git you need to link or copy rclconfig.py and conftree.py from src/python/recoll/recoll to src/filters.

  • Then in the top directory (for a tar archive) or the src/ subdirectory (git), configure and build. The following would install to /usr/local. Use -Dprefix=/some/path if you want to install elsewhere.

    meson setup build -Dx11mon=false -Dwebengine=true -Dsystemd=false
ninja -C build
sudo ninja install

The above will install the recoll GUI command as a regular Posix executable in the appropriate directory (e.g. /usr/local/bin). You can also copy the build/qtgui/recoll.app directory to /Applications to get a regular Mac OS application which you can start from the desktop and link into the dock.

Some Python extensions from the build end up in the wrong place. This is due to a known meson bug. To fix, run the following after the installation:

sudo mv /usr/local/usr/local/lib/python3.13/site-packages/* /usr/local/lib/python3.13/site-packages/

For getting ExifTool (image tags indexing), install cpan with brew, then install Image::Exiftool with cpan.

Also some Python modules necessary for a number of file types are not packaged by Homebrew. For these, I ignored the dire pip3 warnings about breaking stuff and installed them in user mode:

pip3 install --user --break-system-packages lxml
pip3 install --user --break-system-packages mutagen
pip3 install --user --break-system-packages py7zr
pip3 install --user --break-system-packages pyyaml

If things get indeed broken (unlikely because the modules or their dependants don’t appear to be packaged by Homebrew), the install in user mode puts everything in ~/Library/Python/3.13/lib/python/site-packages, which is easy enough to clean up. The alternative would probably be to run Recoll in a Python virtualenv, which I did not try.

antiword and unrtf are packaged by Homebrew.

Hybrid approach

Installing from the Recoll DMG

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

Recoll built on Ventura, Universal Binary and Qt 6.7.3, with Xapian 1.4.29. Should run on both Intel x86 and Apple arm64: recoll-1.43.6-20251014-af2d6350.dmg.

From multiple reports, the app runs on Apple Silicon, but did not test myself.

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.

Note

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.), and PDF. It does not include the Python extension. See further for how to build this.

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. You will probably have file types which are not processed by the default installation. Check the Help→Missing helpers menu.

You will need to install the needed helpers with your preferred method (MacPorts, Homebrew etc.). You will need to reset the index or run a "File→Special Indexing" pass with the "Retry previously failed files" option checked after installing new helpers.

Recoll 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

Building the Python extension

The distributed Recoll app does not include the binary Python extension, as there is no way to know what Python version will be in use on the target system.

Here follows a recipee to build the extension from a Recoll tar distribution. It’s probably better to use a tar distribution version with the same major version as the app (e.g. 1.39.x for 1.39.y), but this is a very loose requirement as only compatibility with the Recoll index format is really needed, and this has not changed for the last 10 years or such. You could just as well use 1.38 or 1.40. The following uses 1.40.3 as an example, you can use the latest distribution instead.

The example supposes that the system is using MacPorts. Something very similar could probably be done with Homebrew.

  • Install the various dependencies in MacPorts. We are going to disable the GUI build and a few other things, so that the list should be something like: meson, xapian-core, libxml2, libxslt, libz, libmagic, iconv

  • Download and extract recoll 1.40.3

  • Prepare the build directory:

    cd recoll-1.40.3
meson setup -Dprefix=/opt/local -Dqtgui=false -Dpython-chm=false \
    -Dpython-aspell=false -Dindexer=false -Dx11mon=false build
cd build

  • On my system there was a problem (meson issue probably) for detecting libiconv, resulting in an "undefined _libiconv_open" error. The workaround was to edit build/ninja.build, and change -liconv into /opt/local/lib/libiconv.dylib

  • Build and install:

    ninja
sudo ninja install

    This will create /opt/local/share/recoll and /opt/include/recoll, and install the recoll dynamic library into /opt/local/lib and the Python extension into /opt/local/lib/python3.12/site-packages. The include files can be deleted, and also the shared data files if you have a main installation somewhere else.

  • Meson and MacPorts don’t agree on the Python lib path: meson installs under /opt/local/lib/python3.12/site-packages, which is not in the MacPorts python3 default libpath. You can work around this by setting the PYTHONPATH environment variable or complementing the path inside your Python program:

    import sys
sys.path.append(`/opt/local/lib/python3.12/site-packages`)
from recoll import recoll

Finally, you will need to set the RECOLL_DATADIR environment variable to the location of the examples shared data files directory, which may be from the installation above or from the main Recoll installation. See this section for more detail.

"Configuration could not be built": locating the shared data files

Because the Recoll bundle is self-contained and could run from anywhere, the programs locate the default configuration files by computing their path relative to their own invocation.

This works fine when the GUI is started by double-clicking the icon, because all execution paths will be absolute.

If you want to start the indexer from the command line, you will also need to use an absolute path, e.g.: /Applications/recoll.app/Contents/MacOS/recollindex

Trying to execute the indexer with a relative path will result in the following:

cd  /Applications/recoll.app/Contents/MacOS/
./recollindex
updateMainConfig: NEW CONFIGURATION READ FAILED. dirs: /Users/dockes/.recoll /Applications/recoll.app/Contents/MacOS/Resources/examples
Configuration problem: Configuration could not be built:
No/bad main configuration file in: [/Users/dockes/.recoll] or [/Applications/recoll.app/Contents/MacOS/Resources/examples]

This error may occur in various circumstances, and may also occur, for example when using the Recoll Python extension. It can be fixed by setting the RECOLL_DATADIR environment variable to the directory above the examples Recoll data directory:

cd  /Applications/recoll.app/Contents/MacOS/
RECOLL_DATADIR=/Applications/recoll.app/Contents/Resources   ./recollindex

Older "hybrid approach" versions

Recoll 1.42.1 built on Ventura, Universal Binary and Qt 6, should run on both Intel x86 and Apple arm64: recoll-1.42.1-20250210-e61b1060.dmg.

Recoll 1.41.0 built on Ventura, Universal Binary and Qt 6, should run on both Intel x86 and Apple arm64: recoll-1.41.0-20241127-18c31eae.dmg.

Recoll 1.40.3 built on Big Sur, Universal Binary and Qt 6, should run on both Intel x86 and Apple arm64: recoll-1.40.3-20241102-e98f27e4.dmg.

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.32 built on Big Sur, Qt 5: recoll-1.32.0-20220311-63d1318d.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.