# Below KOReader v2025.08 Bookshelf shows one menu line and stops

> A KOReader home screen built on top of KOReader's own Cover browser plugin, with shelves that remember their own filters, three ways to draw the grid, and a launcher you assemble yourself. It refuses to run on old firmware, and it depends on a built-in plugin that other plugins ask you to switch off.

**AndyHazz/bookshelf.koplugin** — A nice looking home screen for KOReader. Lets you pick a book from your shelf and read it, with some customisation around the book preview info that's shown.

- Repository: https://github.com/AndyHazz/bookshelf.koplugin
- Stars: 977 · Forks: 38
- Language: Lua
- License: AGPL-3.0
- Published: 2026-09-19 · Updated: 2026-09-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/andyhazz-bookshelf-koplugin

## Below KOReader v2025.08 the plugin prints one line and steps aside

The version requirement is stated as a wall, not a warning. Bookshelf needs KOReader v2025.08 or newer and is said to work best on v2026.03 or newer. On anything older than v2025.08 it shows a single menu line asking you to update, instead of running at all.

Between v2025.08 and v2026.02 it does run, with three named differences: corners on covers and folder cards come out square, staged bulk-edit buttons show no highlight, and opening a book from the quote of the day does not jump to the quote. Those are small, specific regressions rather than a vague compatibility statement, which is a better sign than a blanket promise.

The way to find out which side of the line you are on is Help > Version in KOReader's own menu. That is a deliberate choice to fail loudly rather than to half-render a cover-first interface on firmware that cannot support the rounded corners and staged buttons it expects.

## Cover browser is a hard dependency, and other plugins ask you to turn it off

Bookshelf needs KOReader's Cover browser plugin, which is switched on in a stock installation. The plugin documentation is candid that this is usually nothing to do, and that the only case where it matters is a reader who has turned it off themselves, which some other plugins ask for.

That is the interesting part. Cover browser is what supplies the covers and the metadata Bookshelf reads, so Bookshelf is not an independent source of library data; it is a different front end for the index another plugin maintains. Any theme or helper plugin whose install instructions say to disable Cover browser will, on a reader who follows both sets of instructions, break this one.

The failure mode is gentle. Without Cover browser, Bookshelf shows a one-time notice and steps aside to KOReader's standard file browser. Nothing crashes and nothing is half-drawn, which is the correct handling for a plugin whose data source was pulled out from under it, but it does mean a working library is not enough on its own.

## Installation is one zip unzipped onto three different paths

There are no shell commands anywhere in the installation. You download the latest bookshelf.koplugin.zip from the repository's Releases page, unzip it over your device's KOReader plugins folder, and restart KOReader. Which folder that is depends on the device:

| Device | Plugins folder |
|--------|----------------|
| Kindle | `/mnt/us/koreader/plugins/` |
| Kobo | `/mnt/onboard/.adds/koreader/plugins/` |
| Android | `<koreader-dir>/plugins/` |

Then there is one setting that is easy to miss, Start with set to Bookshelf. Without it KOReader opens its standard file browser on launch, and Bookshelf has to be opened by hand from the menu each time.

The instruction for that setting comes with its own trap worth knowing: Start with appears only in the menu of KOReader's File Manager screen, not while a book is open. If it cannot be found, close the book first, or launch KOReader with nothing open, then open the menu from the file browser. That is the single most likely reason an otherwise correct install appears to have failed.

## Two different menus are both called Bookshelf, and one of them you build

The documentation spends a block of text on a naming collision. Throughout the instructions, menu always means Bookshelf's own menu: the Bookshelf tab in KOReader's top menu, marked with an open-book icon and usually second from the left.

That is not the start menu, which is the hamburger in the bottom-left corner of the shelf and is a launcher you assemble yourself out of shortcuts, folders and live panels. The start menu does carry a Bookshelf menu shortcut back to the same place by default, which is presumably where the confusion comes from.

Once running, the Bookshelf tab holds everything else: shelf size, shelves, Hardcover, updates and settings. The naming is unfortunate but the disambiguation is thorough, and anyone following the instructions will not confuse the two provided they read the note.

## Seven kinds of shelf target, each carrying its own filters and a three-level sort

A shelf is one slice of the library, and out of the box you get Home, Recent, Series and Favorites. Any of them can be renamed, reordered, hidden or deleted, and you can add as many more as you like.

The target is what makes them different. A shelf can point at Home as folders or as a flat list, at Recent or Latest, at a stack of series, authors, genres, collections, formats, ratings or reading statuses which you then drill into, at one specific one of those, at the starred Favorites shelf, at an OPDS catalogue browsed as a shelf with downloads, or on a Kindle at the Kindle's own library.

Each shelf then remembers its own filters, which can be reading status, genre, language, format, rating, collection or folder, plus a sort priority up to three levels deep such as surname then series then series number, and its own label, icon, colour and enabled state. Editing is a long press, the editor footer carries Add new shelf, and the same screen has a Shelf menu font size control. When the shelves overflow the width of the screen the bar pages, with chevrons or a swipe, and the active shelf's page is shown first.

## Search leaves folder names out on purpose, and gives you two switches

The search icon sits at the right of the shelf menu and searches 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 rather than to the start of the list.

Two categories are excluded by default, and both are behind switches in Settings and Library and search. Folder names are left out because in most libraries the folders mirror the author, series and genre stacks, so matching a folder just duplicates the metadata result of the same name. Genres and tags are searched, and can be switched off too, which matters when a common tag keeps crowding out the books you meant; with that off, search matches only titles, authors and series.

On an OPDS shelf the same icon searches the catalogue itself rather than the local library, when the catalogue supports it, so a title lookup covers the whole source instead of the page on screen.

## The top panel has eight sections and the documentation names five of them

The large card above the shelf previews whichever book is focused. Tapping a cover focuses it and the card refreshes with its title, author, description, rating and progress; tapping the card's own cover opens the book.

The card is described as having eight sections you can show, hide or restyle, and the ones spelled out are Status line, sitting at the top right and defaulting to disk space, battery, frontlight, Wi-Fi and time; Rating, five tappable stars that are off by default and can be tapped to set or cleared; Title; Author; and Metadata, a free-form line whose default shows the series. The description of that Metadata default ends there, and the sections after it are not enumerated.

The Rating row being off by default is the notable choice. A star widget that writes back to the book's metadata is the kind of thing that quietly fills a library with one-star rows, and leaving it opt-in costs a tap to enable.

## Three tags in six days, and a tree split into lib/, micromodules/, locale/ and tests/

The release cadence at the end of September 2026 was fast. v5.2.2 was tagged on 2026-09-27, v5.2.3 on 2026-09-28 and v5.3.0 on 2026-10-02, three tags in six days with a minor version bump inside the window. The default branch is master and was pushed to on 2026-10-01.

The layout suggests more care than a single-file plugin usually gets. main.lua sits at the root next to _meta.lua, the KOReader plugin manifest, with the code split into lib/ and micromodules/, translations in locale/, bundled fonts/ and assets/, and separate tests/ and tools/ directories. Fonts and a locale tree are shipped inside the plugin rather than assumed from the device, which explains why the install is a zip rather than a copy of one file.

The repository has no separate homepage and is licensed AGPL-3.0, with a LICENSE file and a .gitattributes at the root.

## Conclusion

Bookshelf is worth trying if you already read on KOReader, want covers instead of a file browser as your landing screen, and are willing to live inside the Cover browser dependency. It is not worth trying if your device is on firmware older than v2025.08, because you get a single menu line telling you to update rather than a partial experience. Three things are worth checking before you rely on it: your KOReader version through Help > Version, that Cover browser is still ticked under More tools and Plugin management, and which release you are actually installing. The project is AGPL-3.0, the default branch is master, and three tags landed in six days in late September 2026, which is a good reason to download a named zip from Releases rather than track the branch.

## FAQ

### What KOReader version does AndyHazz/bookshelf.koplugin need?

KOReader v2025.08 or newer, and it works best on v2026.03 or newer. On anything older than v2025.08 it shows a single menu line asking you to update instead of running. Between v2025.08 and v2026.02 it works with square cover corners, no highlight on staged bulk-edit buttons, and no jump to the quote when opening a book from the quote of the day.

### How do I install AndyHazz/bookshelf.koplugin on a Kobo or Kindle?

Download the latest bookshelf.koplugin.zip from Releases and unzip it over the KOReader plugins folder, which is /mnt/onboard/.adds/koreader/plugins/ on a Kobo and /mnt/us/koreader/plugins/ on a Kindle, then restart KOReader. Set Start with to Bookshelf so it opens on launch.

### Does bookshelf.koplugin need KOReader's Cover browser plugin?

Yes. Cover browser supplies the covers and metadata Bookshelf reads, and it is enabled in a stock KOReader. Without it the plugin shows a one-time notice and steps aside to KOReader's standard file browser. Check it under More tools, Plugin management and Built-in plugins, since some other plugins ask you to switch it off.

### What is the start menu in AndyHazz/bookshelf.koplugin?

It is the hamburger in the bottom-left corner of the shelf, a launcher you build yourself from shortcuts, folders and live panels. It is not the same thing as the Bookshelf tab in KOReader's top menu, which holds shelf size, shelves, Hardcover, updates and settings, although the start menu carries a shortcut to it by default.

### What can a shelf in AndyHazz/bookshelf.koplugin point at?

Home as folders or a flat list, Recent or Latest, a stack of series, authors, genres, collections, formats, ratings or reading statuses, one specific value of those, Favorites, an OPDS catalogue browsed as a shelf with downloads, or on a Kindle the Kindle's own library. Each shelf keeps its own filters and a sort priority up to three levels deep.

## Sources

- [AndyHazz/bookshelf.koplugin on GitHub](https://github.com/AndyHazz/bookshelf.koplugin)
- [Issues](https://github.com/AndyHazz/bookshelf.koplugin/issues)
- [License: AGPL-3.0](https://github.com/AndyHazz/bookshelf.koplugin/blob/master/LICENSE)
- [README](https://github.com/AndyHazz/bookshelf.koplugin/blob/master/README.md)
- [Releases](https://github.com/AndyHazz/bookshelf.koplugin/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/andyhazz-bookshelf-koplugin