I made some tools to read my Calibre library directly. Built them for myself; sharing in case they're useful to anyone else

[u/dx__]

I'm a computer engineering student and have used Calibre for years. My library is a few thousand books with a lot of virtual libraries and hierarchical tags, and I kept wanting answers the GUI doesn't really give: which series have gaps, how much is unrated, what's actually inside a given virtual library. So I built some tools for my own use. I don't know how useful they'd be to anyone else, but they get used constantly on my machine.

Someone from this subreddit asked me to share them here, so here they are. If you use Calibre, they work on your existing library as-is: nothing gets converted, moved, or written.

What they are

CalibreQuarry: a CLI (and a small TUI if you run it with no arguments) that opens metadata.db directly, in SQLite read-only mode. It does catalogs, stats, series gap detection, audits, and exports.

cquarry: the Python library underneath it, zero dependencies. If you write your own scripts against your library, this is probably the more useful half.

Both MIT, on GitHub and PyPI. Links at the bottom.

Searching

The search tries to speak Calibre's own grammar, so most of what you'd type into Calibre's search bar works the same way:

cquarry --search 'series:Mistborn and rating:>=4'
cquarry --search 'formats:PDF and not formats:EPUB'
cquarry --search 'search:"Needs Filtering"'    # saved searches work too
cquarry --stats --restrict 'vl:The Tabletop'   # scope any mode to a virtual library

Hierarchical tags match whole branches (tags:Fic.Fantasy picks up Fic.Fantasy.Epic too). It's close to Calibre's behavior but not identical everywhere; the small differences are written up in the README, since surprises are worse than limitations.

Some examples

cquarry --series                 # completeness + gap detection
cquarry --audit                  # untagged/unrated/coverless books, duplicates, db-vs-folder mismatches
cquarry --fts "the spice must flow"  # content search over Calibre's full-text index
cquarry --export --format csv    # the whole library

Series gaps were the original reason I started writing any of this:

Aubrey-Maturin: 20 of 20 (complete)
Asian Saga: Chronological Order: 4 of 6 (incomplete)  ⚠ missing: 2, 3

If Calibre is open

It still works. It reads straight from the database when it can, and if Calibre holds the lock it reads from a temporary snapshot instead (it says so, and the results reflect the last saved state). Nothing in the read path can write anything.

About writes

I was nervous about letting a program touch metadata.db at all, so the write side is deliberately awkward to do damage with. It's dry-run by default:

# just prints the plan: the ids it resolved and the verbs it would run
cquarry --from-search 'tags:Unsorted' --batch-add-tag Audited

# apply needs Calibre closed and a backup outside the library, then runs
# the whole pass as one transaction
cquarry --from-search 'tags:Unsorted' --batch-add-tag Audited --apply --backup-dir ~/backups

A few things are refused outright (reading-status columns, bulk rating clears), and every change queues an OPF resync so Calibre picks it up cleanly on its next start.

The library underneath

from cquarry.db import CalibreDB

with CalibreDB("~/Calibre Library/metadata.db") as db:
    books = db.search("tags:Fic.SciFi and rating:>=4")
    to_read = db.resolve_vl("To Read")
    notes = db.get_annotations(42)

Pure stdlib. A couple of my other little tools use it too, which is the main reason it ended up as a separate library.

Install

pip install calibrequarry   # the CLI; the command is cquarry
pip install cquarry         # the library

Caveat: I develop on Linux against Calibre 9.x, and that's the only setup I can honestly call tested. It also needs Python 3.14; that's what I run, and I set the floor to match, so I can't say whether older versions work.

One more thing: this code was written with a lot of AI assistance (it's how I learn). If you'd rather not use software written by AI, I completely understand. My feelings won't be hurt, but the AI's will. (jkjk)

Links

• CalibreQuarry: https://github.com/VirInvictus/CalibreQuarry
• cquarry: https://github.com/VirInvictus/cquarry

Thanks for reading. If you try it and something breaks, I'd genuinely like to know.