Baloo - KDE Community Wiki

Baloo is the file indexing and file search framework for KDE Plasma, with a focus on providing a very small memory footprint along with extremely fast searching.

User documentation

User documentation for search types and document properties that Baloo indexes

Ways to communicate

Mailing List: [email protected] (info page)

IRC Channel: #kde-devel on Libera Chat

Phabricator project: https://phabricator.kde.org/project/view/261

Top bugs and feature requests

Bugs: https://bugs.kde.org/buglist.cgi?bug_severity=critical&bug_severity=grave&bug_severity=major&bug_severity=crash&bug_severity=normal&bug_severity=minor&bug_status=UNCONFIRMED&bug_status=CONFIRMED&bug_status=ASSIGNED&bug_status=REOPENED&list_id=1629910&priority=VHI&priority=HI&product=frameworks-baloo&query_format=advanced

Feature requests: https://bugs.kde.org/buglist.cgi?bug_severity=wishlist&bug_status=UNCONFIRMED&bug_status=CONFIRMED&bug_status=ASSIGNED&bug_status=REOPENED&list_id=1629911&priority=VHI&priority=HI&product=frameworks-baloo&query_format=advanced

Indexing limitations

Baloo uses the file metadata extractors in KFileMetadata to get information about each file it indexes. This means for a file's content to be indexed

the file must have a recognizable MIME type
KDE must have an extractor for that MIME type. Use the command-line utility kmimetypefinder5 to determine a file's mime type.
- Due to a glib bug, the MIME type of HTML files can change from text/html to application/x-extension-html. The KDE file metadata extractors don't recognize the latter. That bug has a workaround to reset the MIME types to the usual values.
KFileMetadata uses the aging utilities catdoc, xls2csv, catppt to index content of files using the Microsoft Office Word, Excel, and PowerPoint file formats (source), and these utilities have undocumented limitations (bug 438455).
- catdoc home page
- Debian's bug list for catdoc; RedHat's bug list for catdoc
KFileMetadata does not index file names or file contents in ZIP archives.
KFileMetadata does not index the contents of Open Document Format files that are ZIP archives, nor does it index "flat" Open Document Format files that are complex XML files.

Other limitations:

Baloo doesn't index text files (those whose MIME type is detected as "text/something") over 10 MB (source).
The KFileMetadata extractor for text attempts to convert text to Unicode. If the file uses another encoding, such as iso-8859-1, any file contents after the first character that is invalid in Unicode will not be indexed (bug 440537). You may find the -i option to the file command-line utility useful; it tries to infer the character set of a file, e.g. file -i path/to/myfile.txt. You can use the iconv command-line utility to report invalid encodings and convert encodings to UTF-8.
If a file's modification time is January 1 1970 ("zero" in the Unix epoch) or earlier, baloo will reindex it each time it starts (or you run balooctl check) (bug 456108), and balooshow will be confused about the file's "Mtime" if it is before January 1 1970. As a workaround you can change the file's modification time to something after 1970, e.g. touch -m --date=2022-01-01 path/to/myfile.
Some users report that baloo doesn't properly index some files extracted from zip or JAR files. Try reindexing them (see "Troubleshooting").
Although Baloo stores image metadata attributes such as "description:" and "subject:", searching for terms in these does not work (bug 501615). It seems a Baloo text search will only match terms in the picture's "artist:" and "title:" metadata (and in its filename)

Troubleshooting

If a file does not appear in Baloo search results even though it should match your search:

Enter the terminal command balooshow -x /path/to/file to see what Baloo knows about the files. Sometimes it knows about the existence of the file at that path but not the contents and metadata of the file.
The terminal command balooctl failed prints the first 128 files that it had problems indexing, see if the file is in that list.
Sometimes you can fix problems by manually reindexing the file with baloctl index /path/to/file, but first you should clear the file from Baloo's index with balooctl clear /path/to/file (bug 501613).
kfilemetadata_dump /path/to/file prints metadata that KFileMetadata extracts from files, and so may reveal why Baloo search can't find them; however, it does not print text terms.

Other Baloo pages here

Information may be obsolete.

Using Baloo

Baloo is not an application, but a daemon to index files. Applications can use the Baloo framework to provide file search results. For example, Dolphin's Content search can use Baloo. There is a command-line search utility, baloosearch

KDE System Settings > File Search provides an intentionally limited number of settings. You can make additional adjustments in Baloo's configuration file.

Plasma 6 versions

In some Linux distributions that ship Plasma 6, the latest command-line utilities may have a 6 appended, thus balooctl6, baloosearch6, and balooshow6.

balooctl

balooctl is a CLI command to perform certain operations on Baloo. Enter balooctl --help in a terminal app such as userbase:Konsole to list its available subcommands.