Recoll versions after 1.11 define a Python programming interface, both for searching and creating/updating an index.

The search interface is used in the Recoll Ubuntu Unity Lens and the Recoll Web UI. It can run queries on any Recoll configuration.

The index update section of the API may be used to create and update Recoll indexes on specific configurations (separate from the ones created by recollindex). The resulting databases can be queried alone, or in conjunction with regular ones, through the GUI or any of the query interfaces.

The search API is modeled along the Python database API specification. There were two major changes along Recoll versions:

  • The basis for the Recoll API changed from Python database API version 1.0 (Recoll versions up to 1.18.1), to version 2.0 (Recoll 1.18.2 and later).

  • The recoll module became a package (with an internal recoll module) as of Recoll version 1.19, in order to add more functions. For existing code, this only changes the way the interface must be imported.

We will describe the new API and package structure here. A paragraph at the end of this section will explain a few differences and ways to write code compatible with both versions.

There is a good chance that your system repository has packages for the Recoll Python API, sometimes in a package separate from the main one (maybe named something like python-recoll). Else refer to the Building from source chapter.

As an introduction, the following small sample will run a query and list the title and url for each of the results. It would work with Recoll 1.19 and later. The python/samples source directory contains several examples of Python programming with Recoll, exercising the extension more completely, and especially its data extraction features.

        #!/usr/bin/env python

        from recoll import recoll

        db = recoll.connect()
        query = db.query()
        nres = query.execute("some query")
        results = query.fetchmany(20)
        for doc in results:
        print(doc.url, doc.title)

You can also take a look at the source for the Recoll WebUI, or the upmpdcli local media server, which are both based on the Python API.