# book-searcher: Build a Private Book Metadata Search Index in Rust

> zu1k/book-searcher is a Rust and TypeScript tool for indexing book metadata from CSV files and searching a private library locally. It uses the Tantivy search library to index over 10 million records in roughly one minute and return results in 30 microseconds. It runs as a desktop app, a CLI server, or via Docker.

**zu1k/book-searcher** — Easy and blazing-fast book searcher, create and search your private library.

- Repository: https://github.com/zu1k/book-searcher
- Stars: 6,302 · Forks: 310
- Language: TypeScript
- License: BSD-3-Clause
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/zu1k-book-searcher

## What book-searcher Does and the Problem It Solves

Book-searcher solves a specific and narrow problem: searching a large personal library of book metadata by title, author, publisher, ISBN, extension, language, or ID. The README states that the tool can index metadata for over 10 million books in approximately one minute and return search results in 30 microseconds.

This speed comes from Tantivy, a Rust search library that builds an inverted index over the CSV data. The search index is stored locally in an index/ directory and queries hit that index rather than scanning the raw data on each request. The tool does not host book files and does not download books. It only indexes and searches the metadata fields from the CSV input. Providing the CSV data and the actual book files is the user's responsibility.

## Architecture: Rust Core, TypeScript Frontend, Three Crates

The Cargo.toml at the root defines a workspace with five crates: book-searcher (the CLI and server binary), book-searcher-core (the indexing and search logic), book-searcher-desktop (the Tauri-based desktop application), tantivy-meta-tokenizer (a custom tokenizer for book metadata fields), and tools (utilities). The search core in book-searcher-core uses Tantivy at version 0.21 from workspace.dependencies.

The frontend is a separate TypeScript/JavaScript application in the frontend/ directory, built with pnpm and embedded into the binary by the build process. The Makefile defines the two-step build: first the frontend, then the Rust binary. When the CLI server runs, it serves the web UI at 127.0.0.1:7070 from the embedded frontend assets. The Docker image follows the same pattern: a Node.js stage builds the frontend, a Rust stage compiles the binary, and a minimal Debian image runs the final binary.

The release configuration in Cargo.toml strips symbols, enables LTO, and sets opt-level = 3 with codegen-units = 1, which is a standard approach for minimizing binary size and maximizing search performance in a release build.

## Running book-searcher: CLI, Desktop, and Docker

The recommended path for individual users is the desktop version. Download the pre-compiled installer from the releases page at github.com/book-searcher-org/book-searcher/releases, prepare an index directory as described below, and point the settings menu to that directory.

For the CLI version, download the pre-compiled binary and run:

```bash
book-searcher index -f *.csv
```

This creates an index/ directory from the CSV files in the current directory. Then start the server:

```bash
book-searcher run
```

The server listens on 127.0.0.1:7070. Access http://127.0.0.1:7070/ for the web UI. For Docker deployment using the provided docker-compose.yml:

```bash
mkdir book-searcher && cd book-searcher
wget https://raw.githubusercontent.com/book-searcher-org/book-searcher/master/docker-compose.yml
docker-compose run --rm -v "$PWD:$PWD" -w "$PWD" book-searcher /book-searcher index -f *.csv
docker-compose up -d
```

In Docker mode, the server binds to 0.0.0.0:7070 instead of 127.0.0.1:7070. The docker-compose.yml mounts the index/ directory from the host into the container, so the index persists across container restarts.

## Preparing the CSV Index Data

The CSV input must have these fields in order:

```
id, title, author, publisher, extension, filesize, language, year, pages, isbn, ipfs_cid, cover_url, md5
```

The README notes that users must export and maintain their own book metadata, since the project only provides search functionality. Once the CSV files are in the working directory, running book-searcher index -f *.csv builds the index. You may need to remove an existing index/ directory before re-indexing: rm -rf index.

After indexing, the directory should look like this:

```
book_searcher_dir/
├── index/
│   ├── some index files...
│   └── meta.json
└── book-searcher
```

The index format is opaque to the user; meta.json is written by Tantivy and records index metadata. The two search modes are filter (default, all query constraints must match) and explore (any constraint can match). The API accepts query parameters: /search?limit=30&offset=0&title=TITLE for a simple title search, or /search?limit=30&offset=0&query=title:TITLE extension:epub publisher:PUBLISHER for a compound query with the explore or filter mode selector.

## Building from Source

To build the CLI binary from source:

```bash
make frontend_preinstall frontend
```

```bash
TARGET=release make
```

The Makefile runs pnpm to build the frontend and then cargo to build the Rust binary. Move the resulting binary to the project root directory. For the desktop version:

```bash
make frontend_preinstall
```

```bash
cargo tauri build
```

The desktop version uses Tauri, which requires the platform's native webview. The Tauri build produces platform-native installers. The rust-toolchain file at the repository root pins the Rust toolchain version for consistent builds.

## Limitations, Maintenance Status, and a Comparison

The last push to the zu1k/book-searcher repository was on 2026-03-06. The project has no GitHub releases in the primary repository. The release assets (desktop installers and CLI binaries) are hosted at github.com/book-searcher-org/book-searcher, a separate organization repository, so users who want prebuilt binaries should check there rather than the zu1k source repository.

The design has one structural limitation: the tool provides no mechanism for updating individual records or incrementally adding new metadata to an existing index. Adding new CSV data requires re-indexing from scratch after removing the index/ directory. For a library that changes frequently, this is a meaningful operational cost.

A frequently compared alternative in this space is Calibre, the desktop e-book management application. The qualitative difference is that Calibre is a full library management system with a GUI, format conversion, and metadata editing, while book-searcher is a search-only tool with a minimal web UI and API. Calibre's search is not designed to handle metadata sets at the 10-million-record scale that book-searcher targets. Someone who wants to manage, convert, and edit a personal library should use Calibre; someone who wants to run fast searches over a large external metadata dataset should use book-searcher.

The project is under BSD-3-Clause, which permits use, modification, and redistribution with attribution.

## Conclusion

Developers or researchers who have their own book metadata in CSV format and need fast local search will find book-searcher straightforward to build and run. The tool is explicitly a metadata search and does not host book files; sourcing the CSV data and the actual book files are the user's responsibility. The project is under BSD-3-Clause. The last push to the repository was on 2026-03-06; verify that the Rust toolchain version pinned in rust-toolchain still builds cleanly before adopting it for a new project.

## FAQ

### How do I create a book-searcher index from CSV data?

Place your CSV files in the working directory and run book-searcher index -f *.csv. The tool creates an index/ directory. You may need to remove an existing index with rm -rf index before re-indexing. The CSV must have id, title, author, publisher, extension, filesize, language, year, pages, isbn, ipfs_cid, cover_url, and md5 fields.

### What port does the book-searcher CLI server use?

The CLI server listens on 127.0.0.1:7070 by default. Running via Docker with the provided docker-compose.yml binds to 0.0.0.0:7070 instead, making it accessible on the host network. Access the web UI at http://127.0.0.1:7070/ after starting the server.

### Does book-searcher host or download book files?

No. The README states that the project only provides search functionality. It indexes and searches book metadata from CSV files. Sourcing the CSV data and the actual book files is the user's responsibility.

## Sources

- [Issues](https://github.com/zu1k/book-searcher/issues)
- [License: BSD-3-Clause](https://github.com/zu1k/book-searcher/blob/master/LICENSE)
- [README](https://github.com/zu1k/book-searcher/blob/master/README.md)
- [zu1k/book-searcher on GitHub](https://github.com/zu1k/book-searcher)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/zu1k-book-searcher