Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here


An ebook reader application supporting PDF, DjVu, EPUB, FB2 and many more formats, running on Kindle, Kobo, PocketBook, Ubuntu Touch and Android devices

Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star half bd79095782ee4930099175e5ce7f4c89fa3ddabcd56fffcc7c74f6f2a2d46b27 (1 ratings)
Rated 4.5 out of 5
Subscribe to updates I use koreader

Statistics on koreader

Number of watchers on Github 3695
Number of open issues 368
Average time to close an issue 6 days
Main language Lua
Average time to merge a PR 1 day
Open pull requests 29+
Closed pull requests 12+
Last commit over 1 year ago
Repo Created over 6 years ago
Repo Last Updated over 1 year ago
Size 36.7 MB
Homepage http://koreader.r...
Organization / Authorkoreader
Latest Releasev2018.02.12-nightly
Page Updated
Do you use koreader? Leave a review!
View open issues (368)
View koreader activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating koreader for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)
What people are saying about koreader Leave a review
The ability to turn off embedded styles, landscape mode, calibre integration, pdf file support

Build Status Coverage Status AGPL Licence


Join the chat

KOReader is a document viewer application, originally created for Kindle e-ink readers. It currently runs on Kindle, Kobo, PocketBook, Ubuntu Touch and Android devices. Developers can also run a KOReader emulator for development purposes on desktop PCs with Linux, Windows and Mac OSX.

Main features for users

  • supports multi-format documents including:
    • paged fixed-layout formats: PDF, DjVu, CBT, and CBZ
    • reflowable e-book formats: ePub, fb2, mobi, doc, chm and plain text
    • scanned PDF/DjVu documents can also be reflowed with built-in K2pdfopt
  • use StarDict dictionaries / Wikipedia to lookup words
  • highlights can be exported to Evernote cloud account
  • highly customizable reader view and typesetting
    • setting arbitrary page margins / line space
    • choosing external fonts and styles
    • built-in multi-lingual hyphenation dictionaries
  • supports adding custom online OPDS catalogs
  • calibre integration
    • search calibre metadata on your koreader device
    • send ebooks from calibre library to your koreader device wirelessly
    • browser calibre library and download ebooks via calibre OPDS server
  • can share ebooks with other koreader devices wirelessly
  • various optimizations for e-ink devices
    • paginated menus without animation
    • adjustable text contrast
  • multi-lingual user interface
  • online Over-The-Air software update

Highlights for developers

  • frontend written in Lua scripting language
    • multi-platform support through a single code-base
    • you can help develop KOReader in any editor without compilation
    • high runtime efficiency through LuaJIT acceleration
    • light-weight self-contained widget toolkit with small memory footprint
    • extensible with plugin system
  • interfaced backends for documents parsing and rendering
    • high quality document backend libraries like MuPDF, DjvuLibre and CREngine
    • interacting with frontend via LuaJIT FFI for best performence
  • in active development
    • with contributions from developers around the world
    • continuous integration with CircleCI
    • with unit tests (busted), static code analysis (luacheck) and code coverage test (luacov/coveralls)
    • automated nightly builds available at
  • free as in free speech
    • licensed under Affero GPL v3
    • all dependencies are free software

Check out the KOReader wiki to learn more about this project.

Building Prerequisites

These instructions for how to get and compile the source are intended for a Linux OS. Windows users are suggested to develop in a Linux VM or use Wubi.

To get and compile the source you must have patch, wget, unzip, git, cmake and luarocks installed, as well as a version of autoconf greater than 2.64. You also need nasm and of course a compiler like gcc or clang. If you want to cross-compile for other architectures, you need a proper cross-compile toolchain. Your GCC should be at least version 4.8.

Users of Debian and Ubuntu can install the required packages using:

sudo apt-get install build-essential git patch wget unzip \
gettext autoconf automake cmake libtool nasm luarocks \
libssl-dev libffi-dev libsdl2-dev libc6-dev-i386 xutils-dev linux-libc-dev:i386 zlib1g:i386

If you are running Fedora, be sure to install the package libstdc++-static.

That's all you need to get the emulator up and running with ./kodev build and ./kodev run.

Cross compile toolchains are available for Ubuntu users through these commands:

# for Kindle
sudo apt-get install gcc-arm-linux-gnueabi g++-arm-linux-gnueabi
# for Kobo and Ubuntu touch
sudo apt-get install gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf
# for Win32
sudo apt-get install gcc-mingw-w64-i686 g++-mingw-w64-i686

The packages pkg-config-arm-linux-gnueabihf and pkg-config-arm-linux-gnueabi may block you from building for Kobo or Kindle. Remove them if you get an ld error, /usr/lib/gcc-cross/arm-linux-gnueabihf/4.8/../../../../arm-linux-gnueabihf/bin/ ld: cannot find -lglib-2.0

Mac OSX users may need to install these tools:

brew install nasm binutils libtool autoconf automake cmake makedepend sdl2 lua51 gettext
echo 'export PATH="/usr/local/opt/gettext/bin:$PATH"' >> ~/.bash_profile

The KOReader Android build requires ant, openjdk-8-jdk and p7zip-full. A compatible version of the Android NDK and SDK will be downloaded automatically by ./kodev build android if no NDK or SDK is provided in environment variables. For that purpose you can use NDK=/ndk/location SDK=/sdk/location ./kodev build android.

Users of Debian Jessie first need to configure the backports repository:

sudo echo "deb jessie-backports main" > /etc/apt/sources.list.d/backports.list
sudo apt-get update

For both Ubuntu and Debian, install the packages:

sudo apt-get install ant openjdk-8-jdk

Users on Debian finally need to remove JRE version 7:

sudo apt-get remove openjdk-7-jre-headless

In order to build KOReader package for Ubuntu Touch, the click package management tool is needed, Ubuntu users can install it with:

sudo apt-get install click

You might also need SDL library packages if you want to compile and run KOReader on Linux PC. Fedora users can install SDL and SDL-devel package. Ubuntu users probably need to install the libsdl2-dev package:

Getting the source

git clone
cd koreader && ./kodev fetch-thirdparty

Building, Running and Testing

For emulating KOReader on Linux, Windows and Mac OSX

To build an emulator on your current Linux or OSX machine:

./kodev build

If you want to compile the emulator for Windows run:

./kodev build win32

To run KOReader on your development machine:

./kodev run

To automatically set up a number of primarily luarocks-related environment variables:

./kodev activate

To run unit tests:

./kodev test base
./kodev test front

To run a specific unit test (for test development):

./kodev test front readerbookmark_spec.lua

NOTE: Extra dependencies for tests: busted and ansicolors from luarocks.

To run Lua static analysis:

make static-check

NOTE: Extra dependencies for tests: luacheck from luarocks

You may need to checkout the circleci config file to setup up a proper testing environment. Briefly, you need to install luarocks and then install busted with luarocks. The eng language data file for tesseract-ocr is also need to test OCR functionality. Finally, make sure that luajit in your system is at least of version 2.0.2.

You can also specify the size and DPI of the emulator's screen using -w=X (width), -h=X (height), and -d=X (DPI). There is also a convenience -s (simulate) flag with some presets like kobo-aura-one, kindle3, and hidpi. The latter is a fictional device with --screen_width=1500, --screen_height=2000 and --screen_dpi=600 to help ensure DPI scaling works correctly. Sample usage:

./kodev run -s=kobo-aura-one

To use your own koreader-base repo instead of the default one change the KOR_BASE environment variable:

make KOR_BASE=../koreader-base

This will be handy if you are developing koreader-base and you want to test your modifications with the KOReader frontend. NOTE: this only supports relative path for now.

For EReader devices (kindle, kobo, pocketbook, ubuntu-touch)

To build an installable package for Kindle:

./kodev release kindle

To build an installable package for Kobo:

./kodev release kobo

To build an installable package for PocketBook:

./kodev release pocketbook

To build an installable package for Ubuntu Touch

./kodev release ubuntu-touch

You may checkout our nightlybuild script to see how to build a package from scratch.

For Android devices

A compatible version of the Android NDK and SDK will be downloaded automatically by the kodev command. If you already have an Android NDK and SDK installed that you would like to use instead, make sure that the android and ndk-build tools can be found in your PATH environment variable. Additionally, the NDK and SDK variables should point to the root directory of the Android NDK and SDK respectively.

Then, run this command to build an installable package for Android:

./kodev release android


Please refer to l10n's README to grab the latest translations from the KOReader project on Transifex with this command:

make po

If your language is not listed on the Transifex project, please don't hesitate to send a language request here.

Variables in translation

Some strings contain variables that should remain unaltered in translation. For example:

The title of the book is %1 and its author is %2.

This might be displayed as:

The title of the book is The Republic and its author is Plato.

To aid localization the variables may be freely positioned:

De auteur van het boek is %2 en de titel is %1.

That would result in:

De auteur van het boek is Plato en de titel is The Republic.

Use ccache

Ccache can speed up recompilation by caching previous compilations and detecting when the same compilation is being repeated. In other words, it will decrease build time when the sources have been built before. Ccache support has been added to KOReader's build system. To install ccache:

  • in Ubuntu use:sudo apt-get install ccache
  • in Fedora use:sudo yum install ccache
  • from source:
    • download the latest ccache source from
    • extract the source package in a directory
    • cd to that directory and use:./configure && make && sudo make install
  • to disable ccache, use export USE_NO_CCACHE=1 before make.
  • for more information about ccache, visit:
koreader open issues Ask a question     (View All Issues)
  • about 3 years Wikipedia .zim files
  • about 3 years Error while logging in to Evernote
  • about 3 years absolute font-size values have no effect
  • about 3 years Add multitouch gesture for going up in the directory tree
  • about 3 years Make the "powered off" state customizable
  • about 3 years The file manager forgets the current page
  • about 3 years Koreader integration with GoodReads
  • about 3 years clock displays without prompting when reading pdf files in top right corner
  • about 3 years KA1 frontlight not working
  • about 3 years Smalls .mobi images, and not working footnotes
  • about 3 years FR - Custom suspended message
  • about 3 years ./kodev build error: Makefile:819: recipe for target 'zdir.lo' failed
  • about 3 years Android KR crashing
  • about 3 years FR: Support for natural light on KA1
  • about 3 years Unhighlight is not clickable in dictionary view
  • about 3 years Crash on PocketBook Touch HD with Firmware U5.16.136
  • about 3 years A screen size adjustment bug on e-ink Onyx Boox i86ml
  • about 3 years Automatic Wi-Fi resume sometimes does not resume properly
  • about 3 years Koreader crashes when I attempt to enable wi-fi network
  • about 3 years Cannot use custom css with android version.
  • about 3 years FR - full progress bar (upper) adjustments
  • about 3 years FR - Quick top menu commands (icons) for shutting off of reader and toggling light
  • about 3 years FR - Ability to setup clock within koreader
  • about 3 years Dialog when reopening book at start
  • about 3 years Save history file when highlighting
  • about 3 years Footer hides text
  • about 3 years Protect opening ebook with password
  • about 3 years Translate page - enhancement
  • about 3 years Can't make a screenshot while dictionary window is open
  • about 3 years Kobo Aura HD - frontlight is on after sleep, but only in theory
koreader open pull requests (View All Pulls)
  • refactor readerfooter
  • fix tests
  • Add cursor functionality for inputtext widget
  • Restart Koreader if last instance crashed
  • update koreader-base
  • defaults(refactor): remove global hack in filemanagersetdefaults
  • russian keyboard layout improvement from mergen3107
  • Update kosync plugin
  • Automatically connect WIFI after Kobo has been resumed
  • fixed script to support OSX bash 3.x
  • Patch for wikipedia language
  • Support handling usb hotplug event in kobo
  • update new OTA server & fix plugin check errors
  • Frontlight progress bar
  • StorageStat: Improve Output (#2486)
  • Ask for connection when clicking on Wikipedia
  • Prefix format with "Download " in prompt
  • Remove run twice onPageUpdate() when document is opening
  • Changes to calibre companion
  • Add restart koreader function and ensure FlushSettings event can be delivered to all widgets
  • News downloader atom support
  • Statistics plugin v2 (SQLite)
  • [w.i.p] NewsDownloader externalize download engine
  • [WIP] Pocketbook-suspend plugin
  • Add Android clipboard definition
  • [WIP] Add dictionary download option
  • WIP: Use background runner to restore wifi and check network state
  • [i18n, fix] KoboLight plugin: fix up text issues
  • Speed up page turning on big cre documents
koreader list of languages used
koreader latest release notes
v2018.02.12-nightly koreader-nightly-20180212

Special thanks to @dengste this month for adding natural light support on the Kobo Aura One (#3661, #3679).

You can control the natural light feature on the Kobo Aura One through the regular frontlight widget and the frontlight gesture controller. The latter allows for controlling warmth by swiping on the right of the screen, and is accessible via Tools More plugins Frontlight gesture controller.

Those who read two-column papers might like the new two-column navigation (#3674) by @FranMarelli This does not work in conjunction with scroll mode.

Those willing to experiment can try the new Open with option (#3653, #3678). You can choose which rendering engine to use for files that are supported by multiple rendering engines. Most notably you can choose to use either crengine or MuPDF for EPUB and FB2 files. MuPDF support is still experimental, but it may be faster in some cases. The program can now also directly open .bmp, .gif, .hdp, .j2k, .jp2, .jpeg, .jpg, .jpx, .jxr, .pam, .pbm, .pgm, .png, .pnm, .ppm, .svg, .tif, .tiff, and .wdp (#3651).

Finally, a little clarification on last month's HTML dictionary support. We use MuPDF to render the HTML dictionary results. Unfortunately, MuPDF expects its input to be well-formed XHTML, meaning XML. When the HTML is tag soup instead, KOReader will fall back to a stripped version of the HTML dictionary entry. Should this be the case, you can manually fix up the output by adding a .lua file in the dictionary directory. Further details and a few examples are provided by @poire-z in #3585 as well as #3606 and #3611.

We'd like to thank all contributors for their efforts. Some highlights include:

  • Fix speedup of dictionaries init (#3592) @poire-z
  • Swipe down or tap on top left/right to access left/right reader menu tab directly (#3595) @nagyation
  • Menu: configure number of items per page, wrap entries (#3589) @robert00s
  • OPDS - add confirm when file exist in local destination (#3605) @robert00s
  • HTML dictionary link support (#3603) @TnS-hun
  • Update History and Last open document when move (cut and paste) file (#3607) @poire-z
  • Do not execute background runner if device is suspended (#3608) @Hzj-jie
  • [feat] Add NetworkManager:isConnected() (#3593) @Frenzie
  • Filemanager - sort by percent of book (#3614) @robert00s
  • [UX] Move Go back to previous location up one menu level (#3615) @Frenzie
  • Wikipedia: show images and allow interrupting queries (#3609) @poire-z
  • luasettings: backup previous file and auto-recover (#3625) @poire-z
  • epub metadata: support multiple authors (#3624) @poire-z
  • HtmlBoxWidget: fix selection when starting from end (#3632) @poire-z
  • Bump base: fix gray background instead of white on Kindle (#3634) @poire-z
  • Add MovableContainer: allow moving some widgets (#3636) @poire-z
  • Add menu item for toggling auto_book_status (#3642) @poire-z
  • [UX] Dict: scroll back with tap: go to bottom of prev definition (#3647) @poire-z
  • NewsDownloader: better exception handling and basic redirects (#3652) @mwoz123
  • [feat] Open with: choose which engine to use for file (#3651, #3653, #3678) @Frenzie
  • Menu: speed up rendering of long texts (#3657) @robert00s
  • cre full text search: fix inconsistencies (#3656) @poire-z
  • kobolight.plugin: Support for setting natural light (#3661, #3679) @dengste
  • Show vertical marker at original position when back from link (#3669) @poire-z
  • File manager: added 'Go to letter' (#3664) @robert00s
  • cre cache: allow for disabling compression (#3670) @poire-z
  • [feat] Two-column navigation (#3674) @FranMarelli
  • [fix] larger max font size for crengine (#3676) @Frenzie

Full changelog

v2018.01.10-nightly koreader-nightly-20180110

This release updates MuPDF to the latest 1.12 and adds support for HTML dictionaries thanks to @TnS-hun.

We'd like to thank all contributors for their efforts. Some highlights include:

  • NewsDownloader: wifi off prompt after download (#3395) @mwoz123
  • [UX] Improve ConfigDialog (#3443) @robert00s
  • More contrast settings (#3463) @robert00s
  • Add PocketBook626 (#3472) @mk-f
  • Android: Change screenOrientation to sensorPortrait (#3474) @poire-z
  • [UX] Always show screensaver menu in reader (#3471) @Frenzie
  • [fix] add OSX build prerequisites cmake and makedepend (#3478) @chrox
  • [feat] Add Device:hasClipboard() (#3465) @Frenzie
  • Speedup dictionaries init (#3489) @poire-z
  • Disable Purge .sdr and Delete for currently opened book (#3500) @poire-z
  • [UX] Fix bookstatuswidget truncated at the bottom in landscape (#3498) @robert00s
  • [UX] Option to show dictionary in large window (#3499) @TnS-hun
  • [build] Darwin build of Android port (#3520) @chrox
  • Added Pocketbook 624 alias Basic Touch (#3528) @mk-f
  • Add PB623 alias Touch Lux (#3542) @mk-f
  • MuPDF 1.12 (#3547) @TnS-hun
  • cbt support (#3533) (#3554) @TnS-hun
  • Remove not empty folder (#3562) @robert00s
  • copying file with .sdr (#3563) @robert00s
  • Basic fixes to calibre-sync (#3558) @ToxicFrog
  • New option - create new directory (#3555) @robert00s
  • [fix] small skim problem (#3580) @nagyation
  • HTML dictionary support (#3573) @TnS-hun
  • HTML dict: enable color rendering and per-dict user fix html func (#3585) @poire-z

Full changelog

v2017-10-23-nightly koreader-nightly-20171023

This release supports KOReader on PocketBook631 (Touch HD) thanks to @mk-f.

This release enables DjVu on Android.

We'd like to thank all contributors for their efforts. Some highlights include:

  • kodev: add run android convenience shortcut (#3297) @Frenzie
  • Migrate Goodreads to https (#3298) @robert00s
  • [fix] Avoid multiple refreshes when opening credocuments (#3300) @poire-z
  • [fix] Android screen blackout on first light change (#3303) @Frenzie
  • Fix footer, stats, TOC position with cre in scroll mode (#3304) @poire-z
  • [ReadTimer] Time from now (#3311) @robert00s
  • Add LuaData and Dictionary Lookup History (#3161) @Frenzie
  • Option to disable show bottom menu on top menu activation (#3316) @robert00s
  • [fix, Android] Don't steal frontlight control on start (#3319) @Frenzie
  • Better vertical centering of text in its box @poire-z
  • Normalize some widgets appearance (those using ButtonTable) @poire-z
  • [feat] VirtualKeyboard cursor navigation (#3290) @robert00s
  • Allow for disabling flashing of menu, icons and buttons (#3339) @poire-z
  • Menu (TOC, bookmarks): add padding before right text (#3350) @poire-z
  • kodev: Add $ANDROID_ARCH to enable x86 build (#3353) @Frenzie
  • [android] fix hide nav bar on activity create (#3357) @chrox
  • [Android] Enable DjVu (bump base) (#3358) @Frenzie
  • djvu: enable color rendering (#3361) @poire-z
  • Enable Edit (rename bookmark) when tap on highlight (#3369) @poire-z
  • Android NetworkManager (#3386) @mwoz123
  • NewsDownloader promptWifiOn (#3388) @mwoz123
  • [feat] SkimToWidget chapter markers & next/prev chapter/bookmark (#3389) @robert00s
  • [PocketBook] Use inkview-calls for battery-percentage/charging (#3402) @mk-f
  • PocketBook: Basic device-detection / PocketBook631 (Touch HD) support (#3403)

Full changelog

Other projects in Lua