Bookshelf turns KOReader's file browser into a real bookcase

What Bookshelf changes about KOReader's home screen

KOReader's default opening screen is a file browser: functional, and shaped like a filesystem. Bookshelf replaces it with a home screen built the way readers think. You browse the library by series, author, genre, collection, or any slice you define, tap a book, and the hero card shows its cover, blurb, rating, and progress before you open it. Shelves draw three ways: a grid of covers, a text list, or spines standing edge-on like a real bookcase, which is a small thing that makes an e-ink screen feel less like a document viewer. There is also a start menu you build yourself, a launcher in the bottom-left corner holding your shortcuts, folders, and live panels, and it carries a Bookshelf menu shortcut by default. The plugin is free software under AGPL-3.0, the last push to the repository was on 2026-09-17, and the current releases run from v5.0.6 to v5.0.8.

Installing the plugin on Kindle, Kobo, and Android

The README documents a three-step install. First, download the latest bookshelf.koplugin.zip from the Releases page on GitHub. Second, unzip it onto the device into the folder KOReader scans for plugins. Third, restart KOReader. The three paths the README lists are:

/mnt/us/koreader/plugins/
/mnt/onboard/.adds/koreader/plugins/
<koreader-dir>/plugins/

The first is the Kindle path, the second is Kobo, and the third is the Android layout, where the location depends on where KOReader itself lives. After a restart, open the KOReader menu and set Start with -> Bookshelf. Without that step, KOReader still opens its standard file browser on launch, though Bookshelf stays reachable from the menu. One detail worth knowing before you hunt for the setting: Start with only appears in the menu of the File Manager screen, not while a book is open. If you cannot find it, close the book or launch KOReader without one first.

The Cover browser dependency and its failure mode

Bookshelf does not scan covers itself. It reads covers and metadata from the Cover browser plugin that ships with KOReader, which is switched on in a stock install, so most users do nothing. The interesting part is what happens when it is missing. Some other plugins ask you to disable Cover browser, and if you have, Bookshelf shows a one-time notice and steps aside to the standard file browser instead of misbehaving. The README also documents exactly where to check: open the KOReader menu, then More tools, then Plugin management, then Built-in plugins, and make sure Cover browser is ticked. This is a well-behaved dependency. The plugin degrades to the status quo rather than breaking your library, and the failure is visible on first launch rather than buried in a log.

Shelves: stacks, saved filters, and three-level sorts

Out of the box you get Home, Recent, Series, and Favorites, and every one of them can be renamed, reordered, hidden, deleted, or replaced with your own. A shelf can point at several things: your library as folders or a flat list, a stack of series, authors, genres, collections, formats, ratings, or reading statuses, one specific slice such as a single series, an OPDS catalogue, or, on a Kindle, the books in the Kindle library itself. Each shelf remembers its own filters across reading status, genre, language, format, rating, collection, and folder, plus a sort priority up to three levels deep; the README gives surname, then series, then series number as the example. Label, icon, and colour are per shelf too. Editing is a long-press on the shelf, and the editor footer has an Add new shelf button. When shelves overflow the top bar, it splits into pages you move through with chevrons or a swipe, and on e-ink the change plays as a wipe rather than an animation.

Search and the hero card

The search icon sits at the right of the shelf menu and looks across authors, series, genres, collections, and titles in one pass, grouping results by category. Tapping a result drills into it, and a back-swipe returns you to whichever shelf you were on. Folder names are not searched by default, which the README justifies by noting that folders usually mirror the author, series, or genre stacks, so a folder match would only duplicate the metadata result of the same name. If you move by folder, the toggle lives in Settings, under Library & search, as Include folder names in search results. On an OPDS shelf the same icon searches the catalogue itself when the catalogue supports it. The hero card above the grid previews the focused book and has eight sections you can show, hide, or restyle: a status line with disk space, battery, frontlight, Wi-Fi, and time, a five-star rating where a tap sets or clears a star, title, author, a free-form metadata line that defaults to series and series number, the blurb with a tap-to-scroll viewer, and a strip of tappable tag pills.

OPDS catalogues download straight to the shelf

A shelf can point at an OPDS catalogue, an online book catalogue browsed with the same shelf mechanics as your local library. The README names Project Gutenberg and Standard Ebooks as the examples, with downloads landing directly on your shelf. This turns the home screen into an acquisition surface as well as a library view: you can find a public-domain title, read its blurb, and pull it down without leaving the shelf metaphor. The catalogue search detail matters here too. Because the search icon on an OPDS shelf queries the catalogue server, you can look up a title across the whole catalogue rather than only what has already loaded on screen. The README does not document how many catalogues can be stored or how a partially downloaded book behaves on a slow connection, so treat those as untested ground.

What to run instead, and the limits to expect

The stock alternative is KOReader's own file browser plus Cover browser, which adds covers on top of a folder tree. That pair is fine if you think in directories. The difference with Bookshelf is metadata-first shelves with saved filters and multi-level sorts, which folder browsing has no equivalent for. On limits: the README documents plugin folder paths for Kindle, Kobo, and Android only, so other KOReader platforms are on you to figure out. Search skips folder names by default, a deliberate choice that can still look like missing results. The shelf system is deep, and spine view, the start menu, and the hero card editor each carry their own settings, so the Bookshelf menu is the real control room and the README is long on purpose. None of these are defects. They are the cost of a plugin that replaces a core screen rather than adding a menu item.

Editorial conclusion

Bookshelf fits KOReader readers with libraries organized by series, author, or genre, especially on the Kindle and Kobo devices the README documents. Skip it if you work purely by folder, because the stock browser already does that well. After installing, confirm that Start with -> Bookshelf appears in the File Manager menu and that Cover browser is ticked, since without it the plugin shows one notice and steps aside.

Frequently asked questions

Official sources

1. AndyHazz/bookshelf.koplugin on GitHub
2. Issues
3. License: AGPL-3.0
4. README
5. Releases