Search tool for EPUB e-books
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
tastytea 449e315397
add performance section to readme
4 days ago
cmake CI: Add package generation for openSUSE Leap 15. 1 year ago
dist/termcolor Merge commit '6c33fb4dcebd5464d89ca3fb98bdf23847d81fbf' as 'dist/termcolor' 1 year ago
man Add sub-headings for option categories in man page. 1 year ago
src pass c strings to fmt (…) 2 months ago
tests fix tests (copy paste error) 2 months ago
translations Update german translation. 1 year ago
.clang-format Add .clang-tify and .clang-format. 1 year ago
.clang-tidy clang-tidy: change MinimumVariableNameLength to 2 2 months ago
.cmake-format.json disable cmake-format for now 1 month ago
.drone.yml fix release upload 2 months ago
.editorconfig Clean up .editorconfig. 1 year ago
.gitignore Ignore dap-mode file. 1 year ago
AUTHORS Initial commit. 1 year ago
CMakeLists.txt version bump 0.6.2 2 months ago
CMakePresets.json Make sanitizers optional. 1 year ago
CODE_OF_CONDUCT.adoc Initial commit. 1 year ago
CONTRIBUTING.adoc Update rebuild-commands in translator guide. 1 year ago
CREDITS Update credits. 1 year ago
LICENSE Initial commit. 1 year ago
README.adoc add performance section to readme 4 days ago
screenshot.png Update screenshot. 1 year ago



epubgrep is a search tool for EPUB e-books. It does not operate on lines, but on whole files. All newlines will be replaced by spaces and HTML will be stripped. This means you can search for text spanning multiple lines and don’t have to worry about HTML tags in the text.

epubgrep is licensed under the AGPL-3.0-only. The bundled Termcolor is licensed under the BSD-3-Clause license.


Screenshot of epubgrep, showing the output of 2 book searches.

See man page for more information.


Packaging status


sudo eselect repository enable guru
echo 'app-text/epubgrep' | sudo tee -a /etc/portage/package.accept_keywords/epubgrep
sudo emaint sync -r guru
sudo emerge -a app-text/epubgrep

Debian and Ubuntu

wget -O - | sudo apt-key add -
sudo add-apt-repository 'deb[code name] [code name] main'
sudo apt install epubgrep

Replace [code name] with the code name of your installation. Packages are available for bullseye (Debian 11), buster (Debian 10), focal (Ubuntu 20.04) and bionic (Ubuntu 18.04).

If you get the error message that add-apt-repository was not found, install software-properties-common.

From source


  • Tested OS: Linux

  • C++ compiler with C++17 support (tested: GCC 8/9/10, clang 6/11)

  • CMake (at least: 3.12)

  • Boost (tested: 1.75.0 / 1.65.0)

  • gettext (tested: 0.21 / 0.19)

  • libarchive (tested: 3.5 / 3.2)

  • fmt (tested: 7.0 / 4.0)

  • AsciiDoc (tested: 9.0 / 8.6)

  • Termcolor (tested: 2.0) (If not found, the bundled version is used.)

  • pugixml (tested: 1.11 / 1.8)

  • nlohmann_json (tested: 3.9 / 2.1)

  • Optional

    • Tests: Catch (tested: 2.13 / 1.10)

Install dependencies in Debian or Ubuntu

Or distributions that are derived from Debian or Ubuntu. You will need at least Debian buster (10) or Ubuntu focal (20.04).

sudo apt install build-essential cmake libboost-program-options-dev \
                 libboost-locale-dev libboost-regex-dev libboost-log-dev \
                 gettext libarchive-dev libfmt-dev asciidoc libpugixml-dev \
If nlohmann-json-dev can not be found, try nlohmann-json3-dev.
Install dependencies in openSUSE

Tested on openSUSE Leap 15.3.

sudo zypper install cmake gcc10-c++ rpm-build \
                    libboost_program_options1_75_0-devel \
                    libboost_locale1_75_0-devel libboost_log1_75_0-devel \
                    fmt-devel libarchive-devel pugixml-devel \
                    nlohmann_json-devel asciidoc

Get sourcecode


Download the current release at

Development version
git clone


In a terminal, go to the directory where you unpacked / cloned the source code and then:

cmake -S . -B build
cmake --build build --parallel $(nproc --ignore=1)

To install, run sudo cmake --install build. To run the tests, run ctest --test-dir build.

If you are using Debian or Ubuntu, or a distribution that is derived from these, you can run cpack -G DEB in the build directory to generate a .deb-file. You can then install it with apt install ./epubgrep-*.deb. If you are using a distribution that uses RPM packages, like openSUSE or Fedora, you can generate a package with cpack -G RPM and install it with zypper install ./epubgrep-*.rpm or dnf install ./epubgrep-*.rpm.
CMake options:
  • -DCMAKE_BUILD_TYPE=Debug for a debug build.

  • -DWITH_TESTS=YES if you want to compile the tests.

  • -DXGETTEXT_CMD=String The program to use instead of xgettext.

  • -DFALLBACK_BUNDLED=NO if you don’t want to fall back on bundled libraries.

  • -DWITH_SANITIZER=YES to use sanitizers in debug builds.

Similar projects

  • ripgrep-all can search EPUB files and strips HTML, but does not display page numbers or headings.

  • zipgrep from unzip can search EPUB files but does not strip HTML and does not display page numbers or headings.


A test with a directory containing 3333 EPUBs and 6269 files in total showed this difference between epubgrep-0.6.2 and ripgrep-all-0.9.6:

% hyperfine "epubgrep 'floor' ~/Books" "rga 'floor' ~/Books"
Benchmark #1: epubgrep 'floor' ~/Books
  Time (mean ± σ):     167.246 s ±  3.848 s    [User: 176.251 s, System: 79.107 s]
  Range (min … max):   161.533 s … 173.647 s    10 runs

Benchmark #2: rga 'floor' ~/Books
  Time (mean ± σ):      9.219 s ±  0.506 s    [User: 17.540 s, System: 12.773 s]
  Range (min … max):    8.571 s …  9.923 s    10 runs

  'rga 'floor' ~/Books' ran
   18.14 ± 1.08 times faster than 'epubgrep 'floor' ~/Books'

How to contribute

Read the Code of Conduct.

Reporting bugs or suggesting enhancements

Before reporting a bug, please perform a search to see if the problem has already been reported. If it has, add a comment to the existing issue instead of opening a new one. Same for enhancements. It is helpful to re-run the command producing a bug with --debug and attaching the log file to the bug report. The log file of the last run is usually in ~/.local/state/epubgrep/epubgrep.log.

You can also contact me via E-Mail, XMPP or the Fediverse if you don’t want to open an account.

Pull requests

Please use similar coding conventions as the rest of the project. The basic rule to remember is to write code in the same style as the existing/surrounding code.

Add a copyright line with the year, your name and your email address to the files you edited. Add your name and email to AUTHORS. Unless you don’t want to.

You can also send me your patches via E-Mail, ideally using git send-email.


Creating a new translation

To create a new translation, copy translations/epubgrep.pot to translations/[LANGUAGE ABBREVIATION].po (Replace [LANGUAGE ABBREVIATION] with the correct abbreviation for your language, e.g. “es” if you are translating into Spanish or “pt_BR” if you are translating into Brazilian Portuguese). The pot-file is generated during the build process.

Open your new po file with your favourite text editor, (or you may prefer to use a translation catalog editor like Poedit), and first edit the header section of your file. You will need to replace the text in UPPERCASE with the correct values. The easiest way to work out how to do this is to compare it to another po file that already exists.

Updating your translation

When it is time to update your translation, first update your Git working directory. Then do the following:

cmake --build build
cd translations
msgmerge --update es.po epubgrep.pot

Then open your file and locate the strings that need updating. These will have an empty msgstr or will be marked “fuzzy”.

The translation guide is based on's_Information, licensed under GFDL-1.2-only.