If you just want to skip to the TL;DR version of running recoll on Android, click here.

I have used the recoll information retrieval software for quite some time now for searching through my ever-growing collection of documents (mainly PDF and DJVU files) on the desktop, and it has proven to be quite reliable in quickly finding a paper or book which contains a certain phrase. Ever since I got my Android-powered e-ink reader, I wanted to replicate the same workflow as I have on my desktop, but sadly, recoll was not available for Android…until now!

Recoll running in the EinkBro browser

Thanks to the valuable contributions by various users and developers, recoll is now available as a package on termux, the terminal emulator for Android, and works more-or-less the same way as its CLI desktop counterpart.

As recoll also provides a web frontend, below I will describe in detail how one can get it to work on Android devices.

Installation

F-droid, the alternative app store

As mentioned above, recoll is now available as a package on termux, a terminal emulator application for Android devices. Unfortunately, the Play Store version of termux has not been updated in a while, so one needs to acquire a more recent one from elsewhere.
As Android allows alternative application stores, we can get it from f-droid, an app store containing only free, open-source Android applications. To install it, go to the f-droid page using your Android device, click on “Download f-droid”, and open the downloaded file. Note that you may need to enable installation from “unknown sources” to successfully install it.

Termux

As mentioned earlier, termux is a terminal emulator for devices running Android, which brings a lot of the command-line functionality found on Linux to Android. To install termux, open the f-droid app, click on the find button (🔍 icon), search for “termux”, and finally click on the “Install” button ( icon).

After the installation, open up the termux app, and write pkg upgrade -y, followed by Enter (or ⏎) on the virtual keyboard to update all of the currently-installed packages on termux. Recoll, along with its Python interface, can then be installed by running pkg install recoll-python.

Additional abilities

Recoll is able to index many kinds of files (the full list can be found here), but in order to be able to index the most common ones (such as PDFs), it requires some additional termux packages. Below I will list the most common formats, and the additional packages required to index them, in the format [FORMAT]: [PACKAGE(S)]:

  • PDF: poppler
  • djvu: djvulibre
  • Postscript: ghostscript
  • Image tags: exiftool and perl

Each of the above can of course be installed using pkg install [PACKAGE].

Note: I highly recommend installing the aspell-en package (and any other language packages you may use) for handling spelling approximations (see here for an explanation why it is useful).

Indexing

Recoll requires an index in order to make any search queries; to create an index of the default path(s) (the home directory), you can run:

recollindex

Depending on the size and number of files you are indexing, this operation may take some time; don’t worry, the command is fairly verbose and will let you know what it’s currently doing.

(Optional) customizing directories

By default, termux does not have access to any of the “common” directories on your device; in order to do circumvent this, you need to run termux-setup-storage, and allow access to it in the dialog that appears. This creates a symbolic link to the actual storage in your termux $HOME directory.
Unfortunately, recoll does not follow symbolic links by default; this can be circumvented by either:

  1. setting followLinks = 1 in recoll.conf
  2. explicitly setting topdirs in recoll.conf

To do either of those, you should do the following:

  • create a dir ~/.recoll: mkdir -p ~/.recoll
  • open the file ~/.recoll/recoll.conf: vim ~/.recoll/recoll.conf
  • depending on what you would like to do:
    • add the line followLinks = 1 to the file
    • add the line topdirs = [DIR1] [DIR2] ... to the file, where [DIR1], [DIR2], etc. are the absolute paths to the directories which you want to index

Subsequent runs of the above recollindex command will only update the index, so they should finish fairly quickly.

In case you want to build a completely new index (while deleting any previous ones), use:

recollindex -z

There are quite a few additional options, for which I will just refer you to the man page.

Running the web frontend

(Alternative) installing from PyPI

Instead of the below, you can use the packaged version of it, which I’ve made available on PyPI. It allows you to install the project with only:

pip install recollwebui

Running the web UI is then accomplished with:

recollwebui

In case you would like to specify a port (see also Troubleshooting: Python reports address already in use), you can use:

recollwebui --port [PORT]

instead.

To run the web frontend, you need to first obtain the code; this is most easily performed using git, which can be installed in termux by running:

pkg install git

Then, you should clone the directory using:

git clone https://framagit.org/medoc92/recollwebui.git

Furthermore, the web UI requires some additional Python packages, which can be installed with:

pip install waitress

After this, you can switch to the recollwebui directory with:

cd recollwebui

and finally run the web UI with:

python webui-standalone.py

after which you can switch to your web browser app, and navigate to the address http://localhost:8080.

The UI can be stopped by pressing the Ctrl key, followed by the C key on the on-screen keyboard.

Troubleshooting

Python reports no module named recoll

In case you encounter this error, run the following:

export PYTHONPATH="${PYTHONPATH}:${PREFIX}/lib/python3/dist-packages"

and then run either python webui-standalone.py (if you installed with git) or recollwebui (if you installed from PyPI).

Note: you can also put this in your ~/.bashrc file so you don’t need to re-do it every time you open a new termux shell, using:

echo 'export PYTHONPATH="${PYTHONPATH}:${PREFIX}/lib/python3/dist-packages"' >> ~/.bashrc

Python reports address already in use

You can specify the port number when you start the web UI using:

python webui-standalone.py --port [PORT]

where [PORT] is some number between 1024 and 65535.

Python reports a ResourceWarning about an unclosed file

According to the developers, this is completely harmless (source).

TL;DR version

  • install f-droid on your device
  • update the f-droid repositories (go to the “Updates” tab and swipe down)
  • find (using the 🔍 icon) and install the termux app (using the icon)
  • open the termux app
  • update the packages on termux by running: pkg upgrade -y
  • install the recoll package and its common plugins on termux by running: pkg install -y recoll-python aspell-en poppler djvulibre ghostscript exiftool perl
  • update the recoll index by running: recollindex (optionally customizing the directories to index)
  • install the web user interface by running: pip install recollwebui
  • run the following command in termux: recollwebui --port 9999
  • switch to a web browser app
  • enter the following address in a new tab: http://localhost:9999