librarr

Librarr

*The missing arr for books. Self-hosted book, audiobook, and manga search and download manager -- like Sonarr/Radarr but for your reading library.

Librarr searches all configured indexers in parallel, scores results by confidence, and auto-imports into your Calibre, Audiobookshelf, Kavita, or Komga library. Single ~17MB Go binary, no runtime dependencies — ~14MB RSS idle in a real homelab[^1], typically 10-20× lower than the .NET-based *arr apps.

[^1]: Measured on v1.1.0 in an LXC on Debian 12 (Mar 2026). Reference: Sonarr 4.x ≈ 240MB, Radarr 5.x ≈ 220MB on the same host.

Screenshots

Search	Library

Wanted	Settings

Why Librarr?

• Import your Goodreads or StoryGraph library via CSV and bulk-download everything
• Request workflow -- users request books, admins approve, downloads happen automatically (like Jellyseerr for books)
• Wanted list with quality profiles -- every wanted book is a monitored entity with a state (missing, downloading, upgrade wanted, satisfied); rank formats (EPUB > AZW3 > MOBI > PDF), set a cutoff, and librarr grabs a first copy, then upgrades it until the cutoff is met and retires the old file
• Author monitoring that acts -- follow authors; new works (tracked by Open Library work key, so reissues don't fire) land on the wanted list automatically
• Series auto-complete -- detects gaps in series and searches for missing volumes
• Torznab API -- add Librarr as an indexer in Prowlarr or Readarr (it works both ways)
• OPDS 1.2 feed -- browse your library from any e-reader app
• Tiny footprint -- ~14MB idle RSS, runs comfortably on a Pi or any thermally-constrained mini-PC

Features

Search and Scoring

• Pluggable indexer registry -- driver kinds listed below; default endpoints are fetched at startup from the librarr-sources companion repo and overrideable at runtime via LIBRARR_SOURCES_URL / LIBRARR_SOURCES_PATH
• Confidence scoring -- 0-100 score with breakdown (title match, author match, format, seeders, file size)
• Quality profiles -- per media type, best-first format ranking with a cutoff; formats left out are never grabbed automatically; built-in defaults for ebook / audiobook / manga
• Release profiles -- preferred and excluded words for fine-grained filtering
• Blocklist -- failed downloads are auto-blocked to prevent retries; a release that claimed a better format but delivered the same or a worse one is rejected after import and blocklisted; manual entries supported
• Already-in-library detection -- results you already own are flagged with in_library / library_item_id and badged in the UI; matching normalizes punctuation, author prefixes and parenthetical alternate titles, so Agatha Christie - 4.50 From Paddington finds 4:50 from Paddington

Download Management

• Multiple download clients -- qBittorrent or Transmission for torrents, plus SABnzbd for Usenet
• Anna's Archive membership fast download -- optional account secret key uses /dyn/api/fast_download.json, with LibGen mirror fallback
• Request/approval workflow -- pending, approved, searching, downloading, completed states with per-request notifications
• Scheduled wanted-list searches -- the scheduler searches every monitored wanted item on an interval, runs its quality profile over the results (match score gates, format rank decides) and grabs the best acceptable release; POST /api/scheduler/run?wait=1 runs a pass synchronously
• Torrent completion watcher -- polls download client, auto-imports completed downloads
• Dead letter retry -- failed jobs can be retried individually or in bulk

Library Management

Without Audiobookshelf or Kavita configured, the library tabs show locally imported items with titles, authors, formats, and file sizes. Local library search matches titles and authors across all pages.

• Auto-import pipeline -- organize files by author/title, rename on import (configurable pattern), scan into Calibre/Audiobookshelf/Kavita/Komga
• Series auto-complete -- detect gaps in series, search for and download missing books
• Author monitoring -- follow authors; the first check records their catalogue as a baseline, later checks add each new work to the wanted list (or only notify, per author)
• Reading history -- track what you've read with stats (books per month, pages, completion rate)
• Tags -- organize library items with custom tags for filtering and grouping
• Series grouping -- groups related books/volumes in the library view
• EPUB verification -- checks title word overlap to detect wrong-book downloads

Notifications and Webhooks

• In-app notifications -- persistent alerts for downloads, requests, failures, and author releases
• Discord webhooks -- rich embeds for download events, request updates, and errors
• Generic webhooks -- JSON payloads for any webhook-compatible service
• Configurable events -- choose which events trigger notifications

Import and Export

• Goodreads CSV import -- import your shelves, auto-download "to-read" books
• StoryGraph CSV import -- import your reading list
• Library export -- JSON and CSV export for library, wishlist, and requests
• Backup and restore -- full database backup with one-click restore

APIs and Integrations

• Torznab/Newznab API at /torznab/api -- add as indexer in Prowlarr, Readarr, or any compatible app
• OPDS 1.2 feed at /opds -- browse and download from e-readers (KOReader, Moon+ Reader, Librera)
• Prometheus metrics at /metrics -- request counts, download stats, source health, library size
• REST API -- full JSON API for all operations (see API section below)

Security and Multi-User

• Multi-user auth -- session login with bcrypt passwords and admin/user roles
• TOTP 2FA -- RFC 6238 time-based one-time passwords with QR code setup
• OIDC / SSO -- OpenID Connect for Authelia, Keycloak, Authentik, and others
• API key auth -- X-Api-Key header or ?apikey= parameter for programmatic access
• Rate limiting -- per-endpoint rate limits with configurable thresholds
• Security headers -- X-Content-Type-Options, X-Frame-Options, CORS, request size limits

UI and Admin

• Modern dark UI -- Tailwind CSS, mobile-responsive, single-page app
• Admin dashboard -- library stats, source health, activity log, system info
• Bulk operations -- retry or cancel multiple downloads at once
• File uploads -- drag and drop ebooks/audiobooks, auto-organize and library scan
• Connection tests -- verify Prowlarr, qBittorrent, SABnzbd, Audiobookshelf, Kavita connectivity

Deployment

• Single static binary -- ~17MB, zero CGO, pure-Go SQLite (modernc.org/sqlite)
• Docker-ready -- minimal Alpine image, runs as non-root user
• Cross-platform -- Linux, macOS, Windows; amd64, arm64, armv7

Search Sources

Librarr ships with driver implementations -- the protocols it can speak. The list of active indexers, their endpoints, mirrors, and enabled flags lives in a JSON registry, hosted in the librarr-sources companion repo and fetched at startup (similar to how Prowlarr syncs its indexer definitions). The binary itself ships no embedded registry. After the first successful fetch the registry is cached on disk so subsequent restarts work offline. To use a different registry, set LIBRARR_SOURCES_URL (another HTTP source) or LIBRARR_SOURCES_PATH (a local file).

To add or remove a specific indexer endpoint, edit the registry -- no code changes required.

Quick Start

Docker (recommended)

services:
  librarr:
    image: ghcr.io/jeremiahm37/librarr:latest
    ports:
      - "5050:5050"
    volumes:
      - ./data:/data
      - /path/to/ebooks:/books/ebooks
      - /path/to/audiobooks:/books/audiobooks
      - /path/to/manga:/books/manga
    environment:
      - AUTH_USERNAME=admin
      - AUTH_PASSWORD=changeme
      - API_KEY=your-api-key-here
      - QB_URL=http://qbittorrent:8080
      - QB_USER=admin
      - QB_PASS=changeme
      - PROWLARR_URL=http://prowlarr:9696
      - PROWLARR_API_KEY=your-prowlarr-api-key
    restart: unless-stopped

docker compose up -d

Binary

# Download from releases
curl -LO https://github.com/JeremiahM37/librarr/releases/latest/download/librarr_linux_amd64.tar.gz
tar xzf librarr_linux_amd64.tar.gz

# Configure
export AUTH_USERNAME=admin
export AUTH_PASSWORD=changeme
export QB_URL=http://localhost:8080
# ... set other env vars as needed

# Run
./librarr

Open http://localhost:5050 in your browser.

Configuration

All configuration is via environment variables. Every variable has a sensible default.

Service URLs (ABS_URL, PROWLARR_URL, KAVITA_URL, …) may be written with or without a scheme — audiobookshelf:13378 is normalized to http://audiobookshelf:13378, and trailing slashes are trimmed. The same applies to URLs saved from the Settings UI. Use https:// explicitly when the service is behind TLS.

Server

Authentication

OIDC / SSO

When OIDC_PROXY_HEADERS_ENABLED=true and Librarr sits behind a trusted reverse proxy that injects Authentik headers like X-Authentik-Username, it will treat those requests as an authenticated SSO session, auto-provision the local user if needed, and skip the manual "Login with SSO" click. Enable this only for proxy-gated deployments. Identity headers are honored only when the connection comes from an address in LIBRARR_TRUSTED_PROXIES (e.g. LIBRARR_TRUSTED_PROXIES=172.18.0.5 or a Docker network CIDR). From any other peer they are ignored, and with the list empty they are always ignored — Librarr logs a warning at startup and users fall back to the "Login with SSO" button. Your proxy must also strip these headers from incoming client requests. Local logout only clears Librarr's session cookie; if the proxy keeps sending the identity header, the next request will sign the browser back in.

Download Clients

Librarr sends torrents to either qBittorrent or Transmission. Configure one, or configure both and choose with TORRENT_CLIENT. The category/save-path settings below apply to both (Transmission uses the category as a torrent label, which requires Transmission 3.0+).

Prowlarr

Anna's Archive

Search is currently blocked upstream (August 2026). Anna's Archive sits behind DDoS-Guard, which serves an hCaptcha "I am human" check on /search and /md5/*. This blocks a real browser, not just scrapers, so the annas source returns no results and will report itself unhealthy. The cause is upstream and legal rather than a librarr bug: after the January 2026 lawsuit, Cloudflare disabled the nameservers for several AA domains and the survivors moved to DDoS-Guard, followed by a global domain takedown order.

What this means in practice:

• Search: unavailable. Every surviving domain (.gl, .pk, .gd) behaves the same, and AA publishes no JSON search API — its own API self-documentation (GET /dyn/api/fast_download.json with no parameters) lists fast_download as the only stable endpoint.
• Downloads: still work with a membership key. /dyn/api/fast_download.json is not behind the challenge, so ANNAS_ARCHIVE_SECRET_KEY below still resolves MD5s to download URLs.
• FlareSolverr does not help. It solves Cloudflare, not DDoS-Guard, and times out on the hCaptcha challenge.
• annas-archive.org and .se no longer resolve, and annas-archive.li is an unrelated parked domain — do not point ANNAS_ARCHIVE_DOMAIN at it.

Other sources (Prowlarr, Gutenberg, Open Library, Standard Ebooks, Z-Library) are unaffected.

Library Imports

File Organization

Seeding after import

One setting. For private trackers with seed-time minimums:

REMOVE_TORRENT_AFTER_IMPORT=false

Two separate things have to survive an import for a torrent to keep seeding — its record in the client, and its payload files where the client wrote them. Keeping the record is what that setting says; keeping the payload is what IMPORT_MODE controls. Rather than make you set both, librarr infers the second from the first:

Setting IMPORT_MODE explicitly always wins over that inference — use it to force copy on a filesystem without hardlinks, or hardlink while still removing torrents. IMPORT_MODE=move together with REMOVE_TORRENT_AFTER_IMPORT=false is the one combination that cannot seed; librarr logs a warning at startup if you configure it.

Notes on the modes:

• hardlink costs no extra disk — the library entry and the download folder are two names for the same data, and the space is reclaimed when both are gone. It requires the download folder and the library directories to be on the same filesystem; in Docker that usually means one volume mounted at a common parent (e.g. /data) rather than separate /downloads and /books mounts. When a link cannot be created (different filesystem, or a filesystem without hardlinks such as CIFS/exFAT), librarr logs a warning and copies instead, so the import still lands.
• copy always works but stores the book twice until you delete the torrent. It is also the mode to pick when something else writes to your library files: a hardlinked file is the seeded data, so a tool that rewrites tags in place (some audiobook taggers do) changes the torrent's bytes underneath it and the next recheck fails. Tools that write a new file and rename it are safe, as is librarr itself — it only ever reads imported files or copies them onward.
• With hardlink or copy, if you also leave REMOVE_TORRENT_AFTER_IMPORT=true, librarr removes the torrent and its files once every file is safely in the library — otherwise the payload would sit in the download folder with nothing left to clean it up. The library copy is unaffected (a hardlink keeps the data alive). If any file failed to organize, the payload is left alone.
• Seed goals belong to your torrent client, not to librarr. Once imports hardlink, qBittorrent's own share-ratio / seeding-time limits can be set to "remove torrent and its files" when the goal is met: the download folder is cleaned up on the tracker's schedule and the library keeps the book, because the library entry is a link to the same data rather than a second copy.
• File organization must be on (FILE_ORG_ENABLED=true) for any of this; with it off, librarr indexes files where they already are and never touches them.

Scope. IMPORT_MODE applies to torrent imports and manual imports — the cases where the source may be a live torrent payload. Everything else always moves, because nothing is seeding it and leaving a second copy behind would just accumulate: SABnzbd/usenet imports (librarr never removes anything from the completed folder), web UI uploads, and direct HTTP downloads from sources like Anna's Archive, all of which are librarr's own files.

Sources Registry

Resolution order on startup: LIBRARR_SOURCES_PATH → LIBRARR_SOURCES_URL → built-in default URL → on-disk cache (<LIBRARR_DB_PATH dir>/sources-cache.json) → empty registry. Successful URL fetches are cached so subsequent restarts work offline. If you set LIBRARR_SOURCES_URL, your value replaces the default — it does not stack on top of it.

Legacy per-source env vars (e.g. PROWLARR_URL and other per-driver overrides) continue to be honored and override values loaded from the registry.

Search / Downloads

Feature Toggles

Wanted List & Quality Profiles

These are also editable at runtime under Settings → Wanted List & Quality; values saved there persist in settings.json and override the environment.

Torznab

API Endpoints

Authentication

User Management (admin)

TOTP 2FA

Search

Every result carries in_library (always present), plus library_item_id and library_title when the book is already in your library.

Downloads

All four download endpoints refuse a book that is already in your library with 409 Conflict and {"code": "already_in_library", "library_item_id": N}. Set "force": true on the request to download it anyway (a different edition, a different format); that is what the UI's Download anyway button sends.

Library

Removing a local library item preserves the file on disk and returns linked wanted entries to missing. Local ebooks, audiobooks, and manga all offer a confirmation before removal. Manga displayed from Kavita is managed through the Open in Kavita link; its series IDs are not Librarr item IDs. If Kavita is configured, API callers removing a local manga record must explicitly pass ?source=local with the Librarr item ID.

Requests

Wishlist

A wanted item is never deleted by a grab. It remembers the library file that satisfies it; the scheduler skips it once the file meets the profile's cutoff (or when upgrades are off) and otherwise keeps looking for a strictly better format. Deleting the library file sends the item back to missing; files that arrive by other routes are linked on the next pass by title and author.

Notifications

Quality Profiles

Release Profiles

Blocklist

Series

Authors

Reading History

Tags

Import / Export

Backup / Restore

Scheduler

Webhooks (admin)

Admin

Connection Tests (admin)

System

Torznab / Newznab API

Librarr exposes a standard Torznab API at /torznab/api that can be added as an indexer in Prowlarr, Readarr, or any Torznab-compatible application.

Setup in Prowlarr / Readarr:

1. Go to Settings > Indexers > Add
2. Select "Generic Torznab" (or "Generic Newznab")
3. Set the URL to http://your-librarr-host:5050/torznab/api
4. Set the API Key to your TORZNAB_API_KEY value
5. Test and save

Capabilities: GET /torznab/api?t=caps returns the supported search categories and capabilities.

OPDS Feed

Librarr serves an OPDS 1.2 catalog at /opds for e-reader apps (KOReader, Moon+ Reader, Librera, etc.).

Setup: Add http://your-librarr-host:5050/opds as an OPDS catalog in your e-reader. If auth is enabled, enter your Librarr username and password.

When auth is enabled every /opds route requires credentials (HTTP Basic, a browser session, or the API key). Accounts with two-factor auth enabled, and SSO-only accounts, cannot use their password here: enter the API_KEY value as the password instead (any username). Repeated failed logins from one address are temporarily blocked. Basic auth sends the password with every request, so use HTTPS when the feed is reachable beyond your LAN.

Using Librarr with Claude / MCP

Librarr's REST API is the integration surface, so any Model Context Protocol server can expose Librarr's search, download, and library tools to an LLM (Claude Desktop, Claude Code, Open WebUI, Cursor, etc.). There's no built-in MCP server in Librarr — you wire it into the MCP server you already run.

Auth: every endpoint accepts an X-Api-Key header or ?apikey= query param. Set API_KEY in your docker-compose.yml and reuse it from your MCP server.

Minimal Python example using fastmcp:

# librarr_mcp.py — run as: fastmcp run librarr_mcp.py
import os, httpx
from fastmcp import FastMCP

LIBRARR = os.environ["LIBRARR_URL"]       # e.g. http://librarr.lan:5050
API_KEY = os.environ["LIBRARR_API_KEY"]
HEADERS = {"X-Api-Key": API_KEY}

mcp = FastMCP("librarr")

@mcp.tool()
async def search_books(query: str) -> list[dict]:
    """Search for an ebook across all configured sources."""
    async with httpx.AsyncClient() as c:
        r = await c.get(f"{LIBRARR}/api/search", params={"q": query}, headers=HEADERS)
        return r.json()

@mcp.tool()
async def download_book(result: dict) -> dict:
    """Queue an ebook download. Pass a result object returned by search_books — it
    already contains `source`, `title`, and the source-specific URL field
    (`download_url` / `magnet_url` / `md5` / etc.)."""
    async with httpx.AsyncClient() as c:
        r = await c.post(f"{LIBRARR}/api/download", json=result, headers=HEADERS)
        return r.json()

@mcp.tool()
async def list_downloads() -> list[dict]:
    """List active and recent download jobs with status."""
    async with httpx.AsyncClient() as c:
        r = await c.get(f"{LIBRARR}/api/downloads", headers=HEADERS)
        return r.json()

Register with Claude Desktop / Claude Code (~/.claude.json or claude_desktop_config.json):

{
  "mcpServers": {
    "librarr": {
      "command": "fastmcp",
      "args": ["run", "/path/to/librarr_mcp.py"],
      "env": {
        "LIBRARR_URL": "http://librarr.lan:5050",
        "LIBRARR_API_KEY": "your-api-key-here"
      }
    }
  }
}

The same pattern works for audiobooks (/api/search/audiobooks, /api/download/audiobook) and manga (/api/search/manga, /api/download/torrent). Wrap whichever subset of the API Endpoints above is useful to your assistant.

Architecture

Single static binary, zero CGO dependencies, pure-Go SQLite via modernc.org/sqlite.

cmd/librarr/main.go            Entry point
internal/
  config/config.go              Env var configuration
  db/                           SQLite persistence + migrations
  models/                       Core types (books, downloads, wishlist, requests, etc.)
  api/                          HTTP handlers, router, middleware
    auth.go                     Session auth + bcrypt
    totp.go                     TOTP 2FA (RFC 6238)
    oidc.go                     OpenID Connect / SSO
    search.go                   Search endpoint handlers
    download.go                 Download management
    library.go                  Library CRUD
    requests.go                 Request workflow
    notifications.go            In-app notifications
    qualityprofile.go           Quality profiles
    releaseprofile.go           Release profiles
    blocklist.go                Blocklist management
    tags.go                     Tag management
    history.go                  Reading history
    series.go                   Series detection + auto-complete
    importexport.go             Import/export (JSON, CSV, Goodreads, StoryGraph)
    backup.go                   Database backup/restore
    webhook.go                  Webhook configuration
    opds.go                     OPDS 1.2 feed
    admin.go                    Admin dashboard
    metrics.go                  Prometheus metrics
    csv.go                      CSV bulk import
    ratelimit.go                Per-source rate limiting
    router.go                   Route registration
  search/                       Search source implementations
  download/                     Download manager (qBit, Transmission, Deluge, SABnzbd)
  organize/                     Post-download file organization + library import
  metadata/                     Open Library metadata enrichment
  scheduler/                    Background scheduler, series detector, author monitor
  webhook/                      Webhook sender (Discord + generic)
  torznab/                      Torznab/Newznab API handler
web/
  index.html                    Single-page web UI (Tailwind CSS)
Dockerfile                      Multi-stage Alpine build
.goreleaser.yml                 Cross-platform release builds

License

MIT

Disclaimer

This software is provided for educational and personal use only. Users are responsible for ensuring their use complies with all applicable laws and regulations in their jurisdiction. The developers do not condone or encourage copyright infringement or any illegal activity. This tool does not host, store, or distribute any copyrighted content, and ships with no built-in catalog of indexers -- the list of endpoints to query comes from a user-supplied registry.