dir2opds

dir2opds is a self-hosted OPDS ebook server that turns any folder into a digital library. No database, no Calibre—just point it at your book collection and browse or download via any OPDS-compatible ebook reader or web browser.

---

Table of contents

• What is OPDS?
• Features
• Quick start
• Installation
• Usage
• Caching
• Pagination
• Compatible clients
• Documentation
• Contributing
• License
• Acknowledgments

---

What is OPDS?

OPDS (Open Publication Distribution System) is a standard for cataloging and distributing digital publications. OPDS clients (ebook readers, apps) can discover, browse, and download books from an OPDS server. dir2opds is a lightweight, self-hosted OPDS server that turns a plain directory tree into a personal digital library—no database or complex setup required.

Who is it for?

dir2opds is ideal for anyone who wants a self-hosted digital library without the complexity of Calibre or other database-driven solutions. It is perfect for:

• Home server enthusiasts — Run a personal ebook server on a Raspberry Pi, NAS, or home server
• Ebook collectors — Browse and download EPUB, PDF, MOBI, and more from any OPDS-compatible reader
• Privacy-focused users — Keep your book collection local instead of relying on cloud services
• Developers and sysadmins — Deploy a lightweight, containerized ebook server in seconds

Features

• Self-hosted OPDS ebook server — Run your own digital library at home or on a VPS
• OPDS 1.2 compliant — Works with standard ebook readers and OPDS clients
• No database — Reads directly from your filesystem; no Calibre or extra setup
• Flexible layout — Organize by folders; metadata from EPUB/PDF
• Search — Optional filename search (OpenSearch)
• Covers — cover.jpg / folder.jpg as catalog covers, or extract covers from EPUB files
• Web-friendly — Optional HTML interface for browsing your collection via a web browser
• Pagination — Configurable page size for large catalogs
• Caching — ETag/Last-Modified for conditional requests, gzip compression
• Health endpoint — /health endpoint for monitoring and load balancers
• Structured Logging — Uses log/slog for JSON (default) or text logging
• Multiple formats — EPUB, PDF, MOBI, AZW3, and more via configurable MIME types
• Lightweight — Single binary; ideal for self-hosted setups, headless servers, and containers
• Calibre alternative — Simple, database-free approach to serving ebooks

Quick start

Using Docker (replace v1.11.0 with the latest release if desired):

docker run -d -p 8080:8080 -v ./books:/books --name dir2opds ghcr.io/dubyte/dir2opds:v1.11.0

Then open `http://localhost:8080` in an OPDS client or browser.

**Using Go:**

```bash
go install github.com/dubyte/dir2opds@latest
dir2opds -dir /path/to/books -port 8080

Tip: For best client compatibility, use folders that contain either only subfolders (navigation) or only book files (acquisition), not mixed. This keeps your self-hosted digital library well-organized and easy to browse.

---

Installation

Go install

go install github.com/dubyte/dir2opds@latest

For other installation methods (Docker, Podman, pre-built binaries, etc.), see INSTALLATION.md.

---

Usage

Default: serve ./books on http://0.0.0.0:8080.

dir2opds -dir /path/to/books -port 8080

Options

Legacy Behavior (Pre-v1.10.0)

If you need the old behavior where all files are shown and no metadata is extracted:

dir2opds -dir /path/to/books -hide-calibre-files=false -hide-dot-files=false -extract-metadata=false -show-covers=false

For public servers, also set the base URL:

dir2opds -dir /path/to/books -url https://opds.example.com

---

Caching

dir2opds provides two caching-related options with different use cases:

Default (no flags)

Clients use their default caching behavior. No special headers are sent.

-no-cache — Disable Caching

Forces clients to always fetch fresh data from the server. Useful for:

• Frequently changing libraries (adding/removing books often)
• Ensuring clients always see the latest catalog

dir2opds -dir /books -no-cache

This adds the following headers to every response:

Cache-Control: no-cache, no-store, must-revalidate
Expires: 0

-enable-cache — Enable Conditional Requests

Enables bandwidth optimization through HTTP conditional requests. Useful for:

• Large static libraries that rarely change
• Reducing bandwidth when clients re-fetch the same catalog
• Mobile clients on metered connections

dir2opds -dir /books -enable-cache

This adds the following headers to responses:

ETag: "<hash>"
Last-Modified: <timestamp>

Clients can then send conditional requests:

If-None-Match: "<hash>"
If-Modified-Since: <timestamp>

If the catalog hasn't changed, the server responds with 304 Not Modified (no body), saving bandwidth.

Combining Flags

Using both -no-cache and -enable-cache is not recommended. -no-cache prevents clients from caching anything, so the 304 optimization from -enable-cache would never be used.

---

Pagination

For large libraries, dir2opds paginates catalog feeds to improve performance and reduce bandwidth.

How It Works

• Feeds are split into pages with a configurable number of entries per page
• Each page includes navigation links (first, previous, next, last)
• Clients can request specific pages via the ?page=N query parameter

Configuration

# Default: 50 entries per page
dir2opds -dir /books

# Custom page size: 100 entries per page
dir2opds -dir /books -page-size 100

# Maximum page size: 200 entries
dir2opds -dir /books -page-size 200

# Disable pagination: show all entries
dir2opds -dir /books -no-pagination

Disabling Pagination

For small libraries or when using clients that work better with complete feeds, you can disable pagination entirely:

dir2opds -dir /books -no-pagination

When -no-pagination is set:

• All entries are included in a single feed
• No pagination navigation links are generated
• The ?page=N query parameter is ignored
• Recommended for libraries with fewer than a few hundred books

OPDS Feed Links

When pagination is active, feeds include navigation links:

<feed>
  <link rel="first" href="/?page=1" type="..."/>
  <link rel="previous" href="/?page=1" type="..."/>
  <link rel="next" href="/?page=3" type="..."/>
  <link rel="last" href="/?page=10" type="..."/>
  <!-- entries -->
</feed>

Client Usage

Clients can navigate pages directly:

GET /                    # Page 1 (default)
GET /?page=2             # Page 2
GET /mybook?page=1       # Page 1 of /mybook

---

Compatible clients

These OPDS clients have been tested with dir2opds:

---

Documentation

• Installation
• Changelog
• OPDS specification
• Contributing

---

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for license agreements, development setup, and pull request process.

---

License

This project is licensed under the GNU General Public License v3.0. See LICENSE for the full text.

---

Acknowledgments

• @clach04 — Testing and reporting missing content type for comics.
• @evgeni — FB2 metadata extraction (title, authors, genres, annotation) and tests.
• @kulak — Add podman support.
• @masked-owl — Reporting the HTTP path traversal security issue.
• @mufeedali — Update to push image to ghcr.io.
• @rockavoldy — For the docker command example.
• @thenktor - init files and Makefile improvements.