Librarr

Self-hosted book acquisition, organization, cataloging, Wanted monitoring, and OPDS delivery for homelabs.

Librarr 2.0 is under active development. It is evolving from its Readarr roots into a book-centric, Docker-first personal library application for ebooks, audiobooks, comics, and manga.

Librarr began as a fork of the original Librarr project. Librarr 2.0 is now an independently maintained standalone project and has substantially diverged in architecture, user experience, and roadmap. Original licensing and attribution are preserved.

The project is designed for hobby self-hosters in the same spirit as Jellyfin, Audiobookshelf, Kavita, and Calibre-Web:

polished UI
intuitive onboarding
minimal clicks
sensible defaults
responsive layouts
API-first backend
Docker-first deployment
maintainable, reviewable PR-sized changes

Originally inspired by Readarr.

Current Product State

Librarr 2.0 currently has:

a normalized book-centric schema behind repository selection
first-run administrator setup
a redesigned Librarr 2.0 shell and simplified navigation
Home onboarding for empty libraries
a signed-in Home dashboard with recently added books, attention items, import/download status, library summary, and quick actions
Library & Import settings with guided folder configuration
recursive library scanning
scan progress tracking
scan review with summary cards, search, filters, and collapsible sections
duplicate and already-imported detection
manual-review detection and resolution controls
explicit import actions from scan review results
partial-failure reporting and retry of failed imports
logical book cards that group available formats such as EPUB and MOBI
safe library removal with separate catalog-only and delete-files actions
embedded EPUB cover extraction with local cover caching
local audiobook metadata extraction for MP3/M4B, multi-track grouping, embedded artwork caching, duration/track summaries, and conservative path fallback
opt-in Apple Books audiobook and EPUB/PDF ebook export with safe local handoff copies, export history, and a configurable macOS open -a Books helper
authenticated first-class Delivery downloads for EPUB, PDF, MP3, and M4B
explicit metadata refresh for existing normalized books, including legacy audiobook directory conversion, idempotent summaries, and manual-override conflict reporting
Wanted Books with monitored Prowlarr searches, search history, release inspection, and manual qBittorrent handoff
Wanted/library reconciliation so imported Wanted titles move out of the active queue
expanded User Management with local accounts, roles, status, password resets, and invite codes
rich connection diagnostics for Prowlarr and qBittorrent
rTorrent XML-RPC diagnostics, magnet/raw torrent submission, durable client/hash tracking, client-scoped Remote Path Mappings, and normalized completion imports with durable waiting-for-sync and stability checks (cleanup/removal remains unsupported)
normalized /api/v1 read endpoints
/api/v1 Wanted and Downloads endpoints for new UI/API consumers

In the user interface, Get Book, Get Audiobook, and Get Manga start acquisition from Discover or Wanted releases. Download is reserved for delivering files that already exist in the Library, such as Download EPUB or Download M4B from Book Details.

Direct Delivery supports EPUB, PDF, M4B, and single-file MP3 downloads for authenticated users. Multi-track MP3, MOBI, AZW3, and manga-package downloads are not supported yet. A mobile browser can download an EPUB for manual sharing into Kindle or Send to Kindle; Amazon integration is not included.

OPDS 1.2 catalog browsing and downloads for compatible reader apps
compatibility endpoints for existing legacy behavior
optional Prowlarr and download-client integration

Unfinished UI scaffolding such as Devices, Activity, and send-to-device actions is intentionally hidden until those features are real.

Current Features

First-run onboarding

The first-run workflow is:

Create the first administrator account.
Configure library folders.
Scan the existing library.
Review discovered books.
Explicitly import selected books.

After the first Library & Import save:

Save & Continue disappears permanently.
the standard Settings save action becomes authoritative.
onboarding state survives reloads.
Step 2 remains unlocked.

Scanner

Scanning never imports files. It only discovers and classifies files.

In normalized Librarr 2.0 mode, mounted library folders are not adopted at startup. Legacy background folder scanners are disabled, including the older audiobook folder scanner that wrote directly to library_items. Existing ebooks, audiobooks, and manga mounted into the container become part of Librarr only after an administrator runs the explicit Scan → Review → Import workflow.

The scanner currently supports:

recursive folder scanning
metadata extraction where available
filename fallback
duplicate detection
already-imported detection
manual-review detection
progress tracking
background scan jobs
review payload generation
inline metadata editing before import

Supported formats:

ebooks: epub, pdf, mobi, azw3
audiobooks: m4b, mp3
manga/comics: cbz, cbr, pdf

Review classifications:

Ready
Duplicate
Already Imported
Manual Review
Unsupported
Unreadable

Representative real-world scan results during development were roughly:

29 files found
14 imported
13 duplicates
2 manual review

Treat those numbers as an example, not a benchmark or guarantee.

Library management

In normalized Librarr 2.0 mode, the Library displays one card per logical book. Available formats are shown as compact chips on the card and as individual files in the details view. For example, a single book can show both EPUB and MOBI without appearing as two separate books.

Book details provide two distinct admin actions:

Remove from Library removes the normalized catalog record and leaves files untouched. Those files may return during a future scan.
Delete Book and Files deletes the managed files attached to that book and then removes the catalog record. Librarr only deletes paths already associated with the selected book and only when they resolve inside configured library roots.
Merge Matching Duplicates repairs historical split logical-book records when normalized title and contributor matching show they are the same book.

Librarr does not run automatic destructive repair on startup. Administrators can explicitly repair historical duplicate rows from Book Details and can preview the nested ebook path repair from Settings before any files are moved.

Nested ebook path repair

Older development builds could create cataloged files under a repeated ebook folder such as /books/ebooks/ebooks/.... Manual filesystem moves would break Library and OPDS records because normalized file paths are stored in the database.

Administrators can use Settings → Maintenance → Repair Nested Ebook Paths:

Merge matching duplicate books if needed.
Preview the nested ebook path repair.
Review ready, collision, missing, unsafe, and already-repaired entries.
Run the repair only after taking a backup.
Verify Library and OPDS.
Rescan only if needed.

The repair targets only the configured ebook root plus one repeated terminal segment, for example EbookDir=/books/ebooks repairs /books/ebooks/ebooks/... to /books/ebooks/.... It skips missing files, collisions, unsafe paths, and unknown files that are not represented in the catalog. Scanner imports from /data/incoming remain unmanaged/in-place until a separate organization workflow is implemented.

Review and import

Import is always explicit. Librarr does not automatically import after a scan.

The review UI supports:

metadata editor for manual-review and ready candidates
live destination folder, filename, and import-location preview
validation for missing title/author, invalid year/ISBN, empty destinations, and duplicate filenames
Save, Save & Import, Reset, and Cancel actions

The editor uses metadata already discovered during the scan. It does not perform internet metadata lookup. EPUB files with embedded cover artwork are cached locally and displayed during scan review, manual review, metadata editing, Library, and book details. Unsupported formats or corrupt artwork continue to use the colored placeholder.

The Library book-details Metadata section also includes review-first enrichment tools:

Extract from File reads managed EPUB package metadata and embedded cover artwork from the attached local file.
Match Online searches Open Library using existing identifiers first, then conservative title/author matching.

Both tools show current and proposed values side by side. Users choose the fields to apply; Librarr never silently overwrites catalog metadata and never modifies the ebook file itself. Manual fields are protected unless explicitly selected in the proposal review. Applied metadata is persisted through the normalized LibraryService path, including title, edition title, subtitle, publisher, publication date/year, language, description, tags/genres, author, series, identifiers, and managed covers where available.

User management

Administrators can manage local accounts from Settings:

view users, roles, enabled/disabled status, creation time, and last login
create users directly without invite codes
edit usernames and roles
reset passwords
disable or re-enable accounts
delete non-admin users
generate and revoke invite codes

Once users exist, the SQLite users table is authoritative. AUTH_USERNAME and AUTH_PASSWORD are only used by the legacy zero-user authentication path, so changing those Docker environment variables later does not rename or modify existing database users.

Search and downloads

Librarr can search configured sources and send downloads to supported clients. Prowlarr and qBittorrent are optional integrations; Librarr can start, scan, and manage a local library without them.

When using Docker networking, prefer service hostnames over IP addresses, for example:

http://prowlarr:9696

qBittorrent may be remote over HTTPS. Librarr fetches HTTP/HTTPS torrent files from the configured Prowlarr origin itself and uploads torrent bytes to qBittorrent; magnet links continue to use qBittorrent's URL submission path.

Authentication

Fresh installations start with first-run setup. Librarr does not fabricate a local admin session when the users table is empty.

The first created account becomes:

administrator
enabled
authenticated

Existing installations with users continue through the normal login/session flow.

Planned Features

These are planned or in-progress and should not be treated as completed:

external metadata provider lookup
provider-backed metadata refresh previews
reading progress
collections
author management
series management
OPDS 2.0 improvements
Kavita synchronization
Audiobookshelf synchronization
MOBI/AZW/PDF cover extraction improvements
provider cover downloading
send/download to device
Kindle delivery
scheduled scanning
automatic Wanted grabbing and quality profiles
durable Wanted downloaded/imported linkage beyond library reconciliation

Project Direction

Librarr is not trying to become an enterprise architecture demo. The 2.0 work is focused on a practical personal-library experience:

one logical book can have multiple editions and formats
files are physical representations of books
matching is conservative
ambiguous imports are reviewed instead of silently merged
upgrades and migrations are deterministic and reversible
errors should explain what failed, why, what was attempted, and what the user should do next
unfinished features should be hidden instead of teased

Librarr 2.0 Progress

✅ Vision
✅ Architecture
✅ Schema Foundation
✅ Domain Layer
✅ Repository Interfaces
✅ LibraryService
✅ Repository Switch
✅ Normalized Repository
✅ Migration Design
✅ Backfill Engine
✅ Import Planner
✅ Import Executor
✅ Import Engine Feature Flag
✅ First-run Setup
✅ Empty-library Onboarding
✅ Library Scanner
✅ Review UI
✅ Explicit Import from Review
✅ Manual Review Improvements
✅ Metadata Editor
✅ Connection Diagnostics for Prowlarr and qBittorrent
✅ Wanted Books
✅ Wanted Monitor Search History
✅ Wanted Release Inspection
✅ Manual Wanted Release Handoff
✅ Wanted/Library Import Reconciliation
⬜ Metadata Provider Integration
⬜ Cover Improvements
✅ OPDS 1.2 Catalog
⬜ OPDS v2 / Delivery
⬜ Media Assistant Integration

Connection Diagnostics

Prowlarr and qBittorrent diagnostics now run staged checks similar to Portainer or Unraid:

DNS               ✓
TCP               ✓
HTTPS             ✓
Authenticated     ✓
API Version       2.x
Latency           84 ms

Failure states should be equally specific:

DNS               ✓
TCP               ✗
Timeout after 5 seconds

or:

Connected
Authentication failed (401)
Check API key

Each step reports status, elapsed time where useful, detail text, and an actionable suggestion. Future diagnostics should extend the same engine to Audiobookshelf, Kavita, Komga, SABnzbd, and Transmission.

Wanted Books

Wanted Books are stored as canonical book metadata: title, author, identifiers, language, media type, monitored state, and status. When a Wanted item starts from a Prowlarr/torrent release, Librarr preserves the raw release title, indexer, source, and preferred format separately as origin context instead of using the release name as the book title.

The Wanted monitor can search Prowlarr using clean title/author or identifier queries, record search history, and persist the latest matched releases for inspection. Adding a Prowlarr result from Discover also seeds that exact origin release immediately, so View Releases and manual download are available without another search.

The release viewer is read-first: users can inspect score, indexer, protocol, format, language, size, seeders, age, and selected-release state before taking action. When the user chooses a stored torrent or magnet release, the browser sends only the Wanted id and release id. Prowlarr download URLs stay server-side and reuse the same qBittorrent authentication, save path, category, and safe .torrent upload behavior as Discover downloads.

Manual Wanted downloads move the item to downloading after qBittorrent accepts the handoff. The durable Wanted link is carried through completion and into the import planner, so organization uses the selected canonical title and author before any torrent-release-name fallback. The Wanted list also reconciles against the normalized Library: if a non-final Wanted item now matches an imported book by normalized title, author, and media type, it is marked imported and moves to Completed. This is conservative and does not treat same-author different-title books as imported.

Automatic grabbing and quality profiles are intentionally still future work.

Architecture Overview

flowchart TD
    UI["Web UI"]
    API["REST API"]
    Service["LibraryService"]
    Repo["Selected Repository"]
    Legacy["LegacyRepository"]
    Normalized["NormalizedRepository"]
    Items[("library_items")]
    Books[("books")]
    Editions[("editions")]
    Files[("files")]
    Scanner["Library Scanner"]
    Review["Review Payload"]
    Importer["Import Engine"]

    UI --> API
    API --> Service
    Service --> Repo
    Repo --> Legacy --> Items
    Repo --> Normalized --> Books --> Editions --> Files

    UI --> Scanner --> Review
    Review --> Importer --> Service

Repository selection:

LIBRARR_LIBRARY_REPOSITORY_MODE=legacy      # default
LIBRARR_LIBRARY_REPOSITORY_MODE=normalized  # Librarr 2.0 storage

Import engine selection:

LIBRARR_IMPORT_ENGINE=legacy  # default
LIBRARR_IMPORT_ENGINE=v2      # planner + executor + normalized repository

Docker Quick Start

Docker is the preferred deployment path.

Published GHCR tags follow the source branch:

Production/current main: ghcr.io/jamie75/librarr:latest
Stable Librarr 2 line: ghcr.io/jamie75/librarr:v2
Main branch pin: ghcr.io/jamie75/librarr:main
Dogfood/feature validation: ghcr.io/jamie75/librarr:v2-dogfood

v2-dogfood is intentionally mutable and may change between feature builds. Use latest for production installs, or pin v2 when you want the stable Librarr 2 line without following every latest update.

services:
  librarr:
    image: ghcr.io/jamie75/librarr:latest
    container_name: librarr
    restart: unless-stopped
    ports:
      - "5050:5050"
    volumes:
      - librarr-data:/data
      - /path/to/ebooks:/books/ebooks
      - /path/to/audiobooks:/books/audiobooks
      - /path/to/manga:/books/manga
      - /path/to/incoming:/data/incoming
    environment:
      LIBRARR_PORT: "5050"
      LIBRARR_DB_PATH: /data/librarr.db
      SETTINGS_FILE: /data/settings.json
      EBOOK_DIR: /books/ebooks
      AUDIOBOOK_DIR: /books/audiobooks
      MANGA_DIR: /books/manga
      INCOMING_DIR: /data/incoming
      PROWLARR_URL: http://prowlarr:9696
      QB_URL: https://qbittorrent.example.invalid
      # Remote paths as seen by qBittorrent. These are not Librarr's local
      # INCOMING_DIR staging paths unless both containers share the same path.
      QB_SAVE_PATH: /downloads
      QB_AUDIOBOOK_SAVE_PATH: /audiobooks-incoming
      QB_MANGA_SAVE_PATH: /manga-incoming
      QB_CATEGORY: librarr
      OIDC_PROXY_HEADERS_ENABLED: "false"
    networks:
      - homelab-media

volumes:
  librarr-data:

networks:
  homelab-media:
    external: true

Do not put secrets directly in committed compose files. Use Portainer secrets, an .env file outside version control, or your deployment platform's secret manager.

Start:

docker compose up -d

Open:

http://localhost:5050

Binary Quick Start

export LIBRARR_PORT=5050
export LIBRARR_DB_PATH=./librarr.db
export SETTINGS_FILE=./settings.json
export EBOOK_DIR=/books/ebooks
export AUDIOBOOK_DIR=/books/audiobooks
export MANGA_DIR=/books/manga
export INCOMING_DIR=/data/incoming

./librarr

Open http://localhost:5050 and create the first administrator account.

Configuration

All configuration is via environment variables and persisted settings. UI settings can override startup defaults for Library & Import folders.

Server

Variable	Default	Description
`LIBRARR_PORT`	`5050`	HTTP listen port
`LIBRARR_DB_PATH`	`/data/librarr.db`	SQLite database path
`SETTINGS_FILE`	`/data/settings.json`	Persistent settings file

Authentication

Variable	Default	Description
`API_KEY`		Optional API key for programmatic access
`OIDC_ENABLED`	`false`	Enable OpenID Connect login
`OIDC_PROVIDER_NAME`	`SSO`	Login button label
`OIDC_ISSUER`		OIDC issuer URL
`OIDC_CLIENT_ID`		OAuth2 client ID
`OIDC_CLIENT_SECRET`		OAuth2 client secret
`OIDC_REDIRECT_URI`		Callback URL
`OIDC_AUTO_CREATE_USERS`	`true`	Auto-create users on first OIDC login
`OIDC_DEFAULT_ROLE`	`user`	Default role for OIDC-created users
`OIDC_PROXY_HEADERS_ENABLED`	`false`	Trust identity headers from a reverse proxy

Library and import folders

Variable	Default	Description
`EBOOK_DIR`	`/books/ebooks`	Ebook library folder as seen by Librarr
`AUDIOBOOK_DIR`	`/books/audiobooks`	Audiobook library folder as seen by Librarr
`MANGA_DIR`	`/books/manga`	Manga/comic library folder as seen by Librarr
`INCOMING_DIR`	`/data/incoming`	Import Folder / downloads staging path as seen by Librarr
`MANGA_INCOMING_DIR`	`/data/manga-incoming`	Manga incoming staging path
`FILE_ORG_ENABLED`	`true`	Organize imported files automatically

For remote qBittorrent, QB_SAVE_PATH is the path as seen by qBittorrent. INCOMING_DIR is the synchronized path as seen by Librarr. Librarr translates completed torrent paths beneath QB_SAVE_PATH into INCOMING_DIR before importing.

Download clients

Variable	Default	Description
`TORRENT_CLIENT`		Empty auto-selects qBittorrent when configured; otherwise `qbittorrent`, `transmission`, or configured `rtorrent`
`QB_URL`		qBittorrent Web UI URL
`QB_USER`	`admin`	qBittorrent username
`QB_PASS`		qBittorrent password
`QB_SAVE_PATH`	`/downloads`	Ebook download path as seen by qBittorrent
`QB_CATEGORY`	`librarr`	qBittorrent category for ebooks
`QB_AUDIOBOOK_SAVE_PATH`	`/audiobooks-incoming`	Audiobook download path as seen by qBittorrent
`QB_AUDIOBOOK_CATEGORY`	`audiobooks`	qBittorrent category for audiobooks
`QB_MANGA_SAVE_PATH`	`/manga-incoming`	Manga download path as seen by qBittorrent
`QB_MANGA_CATEGORY`	`manga`	qBittorrent category for manga
`REMOVE_TORRENT_AFTER_IMPORT`	`true`	Remove torrent after successful import; set `false` to keep seeding
`TRANSMISSION_URL`		Transmission RPC URL
`TRANSMISSION_USER`		Transmission RPC username
`TRANSMISSION_PASS`		Transmission RPC password
`SABNZBD_URL`		SABnzbd URL
`SABNZBD_API_KEY`		SABnzbd API key
`SABNZBD_CATEGORY`	`librarr`	NZB category

rTorrent / ruTorrent (Phase 2)

Librarr can validate, submit, and monitor an rTorrent instance through its XML-RPC endpoint, including installations managed by ruTorrent. It does not scrape the ruTorrent UI. Submitted torrents are tracked by client identity and info hash, resolved through client-scoped Remote Path Mappings, and imported through the normalized import engine. Torrent removal and data deletion are not implemented; completed torrents remain available for seeding.

Variable	Default	Description
`RTORRENT_ENABLED`	`false`	Enable rTorrent
`RTORRENT_NAME`	`rTorrent`	Display name
`RTORRENT_URL`		Legacy full HTTP/HTTPS XML-RPC endpoint; retained for compatibility
`RTORRENT_HOST`		rTorrent/ruTorrent hostname, preferred with the fields below
`RTORRENT_PORT`	`443`	XML-RPC port; defaults to 80 when TLS is disabled
`RTORRENT_USE_TLS`	`true`	Construct an HTTPS endpoint
`RTORRENT_URL_PATH`	`/rutorrent/plugins/httprpc/action.php`	XML-RPC URL path
`RTORRENT_USER`		Optional username
`RTORRENT_PASS`		Optional password
`RTORRENT_AUTH_MODE`	`auto`	`auto`, `basic`, or `digest` HTTP authentication
`RTORRENT_TIMEOUT_SECONDS`	`10`	RPC timeout
`RTORRENT_LABEL_FIELD`	`d.custom1=`	Optional custom-field method
`RTORRENT_TLS_VERIFY`	`true`	Verify HTTPS certificates
`RTORRENT_ALLOW_PRIVATE_NETWORKS`	`false`	Allow private/loopback rTorrent endpoints; metadata and link-local addresses remain blocked

HTTP/HTTPS Prowlarr torrent URLs are fetched by Librarr, validated within the existing bounded torrent limits, and uploaded to rTorrent as raw bytes. Magnets are submitted directly. The Prowlarr API key is sent only to the configured Prowlarr origin.

Use Settings → Connection Diagnostics to test the current values. For seedbox paths, configure a Remote Path Mapping from the path reported by rTorrent to the path visible inside Librarr; see docs/rtorrent.md.

ruTorrent installations commonly require HTTP Digest authentication. In auto mode Librarr accepts the expected initial 401 challenge, negotiates MD5/qop=auth Digest authentication, and retries once with a bounded stale-nonce retry. The configured seedbox credentials are never sent to another redirect origin or returned in diagnostics.

Prowlarr

Variable	Default	Description
`PROWLARR_URL`		Prowlarr URL, preferably a Docker hostname such as `http://prowlarr:9696`
`PROWLARR_API_KEY`		Prowlarr API key

Optional integrations

Librarr should function without these integrations. Configure them only when you want those workflows.

Variable	Description
`KAVITA_URL`, `KAVITA_USER`, `KAVITA_PASS`	Optional Kavita integration
`ABS_URL`, `ABS_TOKEN`, `ABS_LIBRARY_ID`	Optional Audiobookshelf integration
`KOMGA_URL`, `KOMGA_USER`, `KOMGA_PASS`	Optional Komga integration
`CALIBRE_LIBRARY_PATH`, `CALIBRE_URL`	Optional Calibre / Calibre-Web integration

Sources registry

Librarr loads search-source endpoint definitions from a small JSON registry at startup. See docs/source-registry.md for dependency details, override options, and offline behavior.

Variable	Description
`LIBRARR_SOURCES_URL`	URL of a JSON sources registry
`LIBRARR_SOURCES_PATH`	Local sources registry JSON path; takes precedence over URL

Feature flags

Variable	Default	Description
`LIBRARR_LIBRARY_REPOSITORY_MODE`	`legacy`	`legacy` or `normalized`
`LIBRARR_IMPORT_ENGINE`	`legacy`	`legacy` or `v2`
`METRICS_ENABLED`	`true`	Enable Prometheus metrics
`WISHLIST_CLEANUP_ENABLED`	`false`	Conservative wishlist cleanup task
`WISHLIST_CLEANUP_DRY_RUN`	`true`	Log cleanup matches without deleting

API

Prefer Librarr 2.0 endpoints for new integrations.

Librarr 2.0 read API

Method	Path	Description
GET	`/api/v1/library/summary`	Normalized library totals
GET	`/api/v1/books`	List logical books
GET	`/api/v1/books/{id}`	Book details
GET	`/api/v1/books/{id}/files`	Files for a book
GET	`/api/v1/books/{id}/editions`	Editions for a book
GET	`/api/v1/books/{id}/cover`	Stored local book cover
GET	`/api/v1/books/{id}/download/{format}`	Authenticated download of an EPUB, PDF, MP3, or M4B file
GET	`/api/v1/books/{id}/metadata`	Effective metadata
PATCH	`/api/v1/books/{id}/metadata`	Partial metadata update
POST	`/api/v1/books/{id}/metadata/extract`	Build a review proposal from a managed local ebook file
POST	`/api/v1/books/{id}/metadata/matches`	Search online metadata providers and return review candidates
POST	`/api/v1/books/{id}/metadata/apply`	Apply selected fields from a server-issued metadata proposal
GET	`/api/v1/books/{id}/provenance`	Metadata provenance
GET	`/api/v1/downloads`	Active and recent downloads/import jobs

Wanted Books

Method	Path	Description
GET	`/api/v1/wanted`	List Wanted books and counts
POST	`/api/v1/wanted`	Add a Wanted book
PATCH	`/api/v1/wanted/{id}`	Update monitored state or status
DELETE	`/api/v1/wanted/{id}`	Remove a Wanted book
POST	`/api/v1/wanted/search`	Search all monitored Wanted books
POST	`/api/v1/wanted/{id}/search`	Search one Wanted book
GET	`/api/v1/wanted/history`	Recent Wanted search activity
GET	`/api/v1/wanted/{id}/releases`	Stored releases from latest successful search/origin seed
POST	`/api/v1/wanted/{id}/releases/{release_id}/download`	Manually hand off one stored torrent/magnet release

Scanner, review, and import

Method	Path	Description
POST	`/api/v1/library/scan`	Start a scan job
GET	`/api/v1/library/scan/{id}`	Scan job progress
GET	`/api/v1/library/scan/{id}/cover/{candidate_id}`	Temporary local scan-review cover
GET	`/api/v1/library/scan/{id}/results`	Completed review payload
POST	`/api/v1/library/scan/{id}/resolve`	Resolve or edit a review candidate before import
POST	`/api/v1/library/import`	Start explicit import from scan results
GET	`/api/v1/library/import/{id}`	Import job progress
GET	`/api/v1/library/import/{id}/results`	Import completion results

OPDS catalog

Librarr exposes an OPDS 1.2 catalog for compatible ebook reader apps on:

https://your-librarr.example.com/opds

Use the same Librarr username and password you use for the web app. OPDS endpoints use HTTP Basic authentication because many reader apps cannot use the browser session-login flow. API-key access remains available for scripted clients, but generated catalog URLs never include credentials.

The catalog includes:

root navigation
all books
recently added books
authors
search
cover links when Librarr already has a local cached cover
one acquisition/download link for each available file format

Format behavior:

EPUB and PDF are offered with standard reader-friendly MIME types.
MOBI and AZW3 are offered as raw downloads when present.
CBZ, CBR, MP3, and M4B may be listed for compatible clients, but Librarr does not claim universal iOS reader support for those formats.

Use HTTPS when exposing OPDS outside your local network. Apple Books itself is not an OPDS catalog client; install an OPDS-compatible reader app and add the /opds URL there. Reading progress sync, annotations, highlights, bookmarks, format conversion, and send-to-device workflows are not implemented yet.

Compatibility APIs

These routes still exist for legacy UI behavior, old clients, and transition work. Do not treat them as the preferred long-term domain model.

Method	Path	Description
GET	`/api/library`	Compatibility ebook library list
GET	`/api/library/audiobooks`	Compatibility audiobook list
GET	`/api/library/manga`	Compatibility manga list
GET	`/api/stats`	Compatibility stats
POST	`/api/import/scan`	Legacy manual-import scan
POST	`/api/import/files`	Legacy manual-import execution
POST	`/api/import/csv`	CSV import
GET	`/api/search`	Search ebooks
GET	`/api/search/audiobooks`	Search audiobooks
GET	`/api/search/manga`	Search manga
POST	`/api/download`	Direct download
POST	`/api/download/torrent`	Torrent download
GET	`/api/downloads`	Download jobs; `/api/v1/downloads` is preferred for new clients
GET	`/api/settings`	Settings
POST	`/api/settings`	Save settings
POST	`/api/v1/books/{id}/apple-books/export`	Export a normalized audiobook or EPUB/PDF ebook for Apple Books (admin)
GET	`/api/v1/books/{id}/apple-books/exports`	Export history for one audiobook
GET	`/api/v1/apple-books/exports`	Recent Apple Books export history
GET	`/api/config`	Bootstrap config
GET	`/api/health`	Health check

UX Principles

Home should be simple, minimal, and guiding. Settings sections own their own save behavior. The scanner workflow should be:

Scan → Review → Import → Done

Import is always explicit.

Errors should explain:

what failed
why it failed when known
what Librarr attempted
what the user should do next

Avoid generic "Something went wrong" messages.

Documentation Map

VISION.md — product direction
ARCHITECTURE.md — target architecture and boundaries
ROADMAP.md — milestone tracking and next work
ACKNOWLEDGMENTS.md — origin and attribution
CHANGELOG.md — release history
docs/releasing.md — release and Docker image process
docs/INDEPENDENCE_READINESS.md — fork-detachment readiness
docs/source-registry.md — source-definition dependency and override behavior
docs/library-scanner-phase1.md — scanner, review, and import workflow
docs/import-executor.md — normalized import execution and idempotency
docs/metadata-engine.md — metadata provenance and override behavior
docs/read-api.md — normalized read API
docs/normalized-repository.md — normalized repository behavior
docs/wanted-books.md — Wanted monitoring, release inspection, and manual handoff
docs/apple-books-export.md — safe audiobook and EPUB/PDF ebook handoff to Apple Books
docs/v2-dogfood.md — local Librarr 2.0 dogfood deployment
docs/backfill-design.md and docs/backfill-engine.md — migration/backfill design

Development

go test ./...
go vet ./...
node --check web/static/js/app.js
node --test web/static/js/app.test.js

See CONTRIBUTING.md for contribution expectations.

Name		Name	Last commit message	Last commit date
.github		.github
cmd/librarr		cmd/librarr
docs		docs
e2e		e2e
internal		internal
scripts		scripts
web		web
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.goreleaser.yml		.goreleaser.yml
ACKNOWLEDGMENTS.md		ACKNOWLEDGMENTS.md
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
ROADMAP.md		ROADMAP.md
SECURITY.md		SECURITY.md
VISION.md		VISION.md
docker-compose.v2-dogfood.yml		docker-compose.v2-dogfood.yml
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum
staticcheck.conf		staticcheck.conf

Latest commit

History

Folders and files

Repository files navigation

Librarr

Current Product State

Current Features

First-run onboarding

Scanner

Library management

Nested ebook path repair

Review and import

User management

Search and downloads

Authentication

Planned Features

Project Direction

Librarr 2.0 Progress

Connection Diagnostics

Wanted Books

Architecture Overview

Docker Quick Start

Binary Quick Start

Configuration

Server

Authentication

Library and import folders

Download clients

rTorrent / ruTorrent (Phase 2)

Prowlarr

Optional integrations

Sources registry

Feature flags

API

Librarr 2.0 read API

Wanted Books

Scanner, review, and import

OPDS catalog

Compatibility APIs

UX Principles

Documentation Map

Development

About

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages