KOReader: a Lua document viewer for e-ink readers, from Kindle to Kobo

What KOReader solves that stock firmware does not

Most e-reader firmware treats PDF as a picture of a page. You can zoom, and you can pan, and that is roughly the end of it. KOReader's README describes the project as "a document viewer primarily aimed at e-ink readers" and lists both fixed page formats (PDF, DjVu, CBT, CBZ) and reflowable ones (EPUB, FB2, Mobi, DOC, RTF, HTML, CHM, TXT) in the same application. The interesting part is the overlap: scanned PDF and DjVu files can be reflowed through a bundled K2pdfopt library, so a scanned book is not locked to its original page geometry.

The audience is narrower than "anyone with an e-reader". It is people who already own a device and are unhappy with the software on it, plus people who want one reading application across a Kobo, an Android phone and a Linux laptop. The README lists Cervantes, Kindle, Kobo, PocketBook, reMarkable, Android and Linux computers, and notes that developers can run a KOReader emulator on Linux and macOS. iOS is not in that list and no iOS asset appears in the releases, so the search interest in a KOReader iOS build has nothing to install yet.

The trade-off is real. You are replacing vendor firmware behaviour, including whatever sync and store integration came with the device, with a volunteer-built application. That is the whole point for some readers and a dealbreaker for others.

How KOReader is put together: Lua on top of a C base

The repository is a Lua application with a separate native layer. The top level holds reader.lua, setupkoenv.lua, defaults.lua and datastorage.lua, alongside frontend/, plugins/, platform/, resources/, l10n/ and spec/. The Makefile pulls in base/Makefile.defs from a koreader-base submodule, which is where the platform-specific build definitions live. That split matters when you build rather than download: the version string comes from the main repository, and the Makefile comments say this explicitly, because the base has its own history.

At runtime the application is assembled, not compiled into one binary. The Makefile defines INSTALL_FILES as reader.lua, setupkoenv.lua, frontend, resources, defaults.lua, datastorage.lua, l10n, tools, README.md and COPYING, and links them into an install directory named koreader-$(DIST)-$(MACHINE). If TARGET is not set, DIST defaults to emulator. So a desktop build and a Kobo build differ mainly in which platform directory and which base binaries are selected, while the Lua frontend is the same tree.

Extensibility follows from that layout. The README lists plugins as the extension mechanism, and the plugins/ directory sits next to frontend/ rather than inside it. The README also mentions an FTP client, an SSH server, OPDS catalog support, RSS feeds, StarDict dictionaries, Wikipedia lookup, Wallabag, Google Translate and calibre integration. Those are features of the application, not separate services you have to run.

Installing KOReader on a Kobo, Kindle or Android device

The README does not give a single install command. It sends you to model-specific wiki pages for Android, Cervantes, Kindle, Kobo, Linux, PocketBook and reMarkable, and the release assets are on the GitHub releases page. Start by identifying your exact model and reading that page, because the steps differ: some devices need a jailbreak or a developer mode first, others accept a package copied to the device storage. The README does not document rollback, so treat the first install as the point of no easy return.

For a desktop Linux machine or an emulator build, the workflow is a make invocation. The Makefile defaults DIST to emulator when no TARGET is given, and INSTALL_DIR defaults to koreader-$(DIST)-$(MACHINE), so a plain build produces a self-contained directory rather than scattering files.

make

That target fetches third-party code and builds the base, so expect it to take a while on a first run. The Makefile declares fetchthirdparty and update among its phony targets, which is where dependency retrieval happens.

Once you have a build directory, the entry point is reader.lua. The Makefile lists it in INSTALL_FILES, which is why the installed tree can be launched directly. The README does not give a launch command for the emulator, so check the developer documentation before running anything.

reader.lua

The first real use is opening a scanned PDF and trying the reflow path. The README states that scanned PDF and DjVu documents can be reflowed with the built-in K2pdfopt library, and that page margins, line spacing, external fonts and hyphenation dictionaries are configurable. Set a margin and a font before judging the result, because reflow output depends heavily on both. If you use calibre, the README describes metadata search, wireless book transfer and OPDS library browsing as integrated features, so the first useful check after install is whether your calibre library appears over OPDS.

Where KOReader is the wrong choice

KOReader is not a storefront and the README makes no claim about DRM. If your library comes from a vendor store and is wrapped in DRM, this is not the application that opens it. Nothing in the README suggests a workaround, and treating it as one is a misreading of the project.

The second limit is platform. The supported list is Cervantes, Kindle, Kobo, PocketBook, reMarkable, Android and Linux. macOS appears only in the context of running an emulator for development, not as a target for readers, and iOS is absent entirely. If you need a reader on an iPad, this project does not offer one, regardless of how often the question is asked.

The third is the update path. The README advertises over-the-air software updates, but it does not describe what happens if an update fails on a device, and it does not document rollback. On a phone that is an inconvenience. On a Kobo whose internal storage also holds your library, it is a risk you should price in before flashing.

Finally, the README's performance claim is scoped: "on some older devices, it has been measured to have less than half the page-turn delay as the built in reading software." That is a statement about some older devices, not a general claim, and it says nothing about newer hardware where stock firmware may already be fast enough that the difference does not matter to you.

KOReader compared with calibre's viewer and with stock firmware

The closest thing to an alternative in the README is calibre, but calibre is not a competitor here. KOReader integrates with it: metadata search, wireless ebook transfer and OPDS library browsing. Calibre's own viewer runs on a desktop and is built around managing a library on a computer. KOReader runs on the device you read on and is built around rendering a page on a small e-ink screen with no animation. If your problem is cataloguing, calibre solves it. If your problem is that the PDF on your Kobo is unreadable at any zoom level, calibre does not.

The other alternative is the firmware that shipped with your device. Stock readers on Kindle and Kobo are tuned for their own stores, their own sync and their own format handling, and they are updated by the vendor. KOReader gives up that integration for typesetting control, format breadth and plugins. The README's own framing supports this reading: it calls the UI "custom" and "without animation, with paginated menus, adjustable text contrast", which is a description of a reader built for a slow display rather than a general-purpose app.

A third comparison is with other open source readers that target the same hardware. The README does not name any, so there is no basis here for a feature-by-feature comparison. What can be said is that KOReader's distinguishing structural choice is Lua plus a shared base across embedded devices and Android, which is why one project covers a Kobo and a phone.

Licence, maintenance and what an upgrade actually costs

KOReader is licensed under AGPL-3.0, and COPYING sits at the repository root and is listed in INSTALL_FILES, so it ships with the installed tree. The practical consequence for most readers is nil. For anyone modifying the code and letting others use it over a network, the AGPL's source-availability terms are the part to read. That is a description of the licence, not legal advice; if you plan to redistribute a modified build, read COPYING and take your own counsel.

The project is not archived, and the last push to master was on 2026-09-20, one day before this writing. Releases are dated and named: v2026.07.1 on 2026-08-01, v2026.07 "Sailing Walrus" on 2026-07-26, and v2026.03 "Snowflake" on 2026-03-17. The version scheme is visible in the Makefile, which derives VERSION from git describe and appends the release date when the tag is not a whole version, so a build from a commit between releases carries a date suffix.

Upgrade cost depends on how you installed. On devices with over-the-air updates, the README lists that as a feature and the upgrade is the vendor-independent part of the workflow. On a self-built emulator or desktop install, you rebuild and replace the directory; the Makefile's update and update-% targets exist for refreshing dependencies. The cost that is not documented anywhere in the README is what a failed upgrade leaves behind on an embedded device. Budget for a backup of your device storage before you update, and check the wiki page for your model rather than assuming the generic path applies.

Editorial conclusion

Adopt KOReader if you read PDF or DjVu on an e-ink device and want margins, line spacing, external fonts and dictionaries under your own control, or if you want the same reader on a Kobo and an Android phone. Do not adopt it expecting a store, DRM support or a supported iOS build; the README points to Android, Cervantes, Kindle, Kobo, Linux, PocketBook and reMarkable only. Before flashing anything, check the install page for your exact model, confirm which release asset matches it, and read the update section of the user guide, because the README does not document rollback once a build is in place.

Frequently asked questions

Official sources

1. koreader/koreader on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases