KOREADER USER GUIDE
Last Updated: 2023-10-12

This guide is designed for larger screens with color and contains links to relevant websites so we highly recommend reading this on a computer or a tablet (instead of your e-ink device). You can use the search function of your browser (generally Ctrl+F) to find a specific topic.

Parts of the text are color coded according to their category:

BLUE • USER INTERFACE ELEMENTS OF KOREADER
GREEN • MENU PATHS
RED • ADVANCED TOPICS, NOTES AND WARNINGS
PURPLE • EXTERNAL APPS AND SERVICES
TEAL • LINKS
KOReader is developed and supported by volunteers all around the world. You can be a part of this project too by: Check MORE INFO section at the end for the links.
TABLE OF CONTENTS
WHAT CAN YOU DO WITH KOREADER ?
Despite its minimalistic looks, KOReader is a very powerful and customizable application. Check the list below to see what can you do with KOReader. All these features are explained in this guide.

Transferring your files Text adjustments While reading Navigating through your collection Navigating through your book Search, Lookup and Translation Device settings PDF documents Advanced features Exporting your notes and highlights
USER INTERFACE
KOReader has a simple, mainly black and white user interface because gradients and different shades of gray can cause flashing and ghosting on e-ink screens which can degrade reading experience.

KOReader has 2 main interfaces: READING SCREEN and FILE BROWSER.

Reading Screen
READING SCREEN has two toolbars. TOP MENU includes menu items related to the general usage of KOReader. You will access your books, KOReader preferences, plugins etc. here. BOTTOM MENU is focused on options for document formatting like font weight/size, line spacing etc. While adjusting your text appearance, you will mostly interact with the BOTTOM MENU.

On the right you can see the default tap zones of KOReader. To show the TOP MENU or BOTTOM MENU you can tap the indicated zones. You can also swipe down the upper zone to show the TOP MENU. On non-touch devices like Kindle 4 you can open the BOTTOM MENU by pressing the button that corresponds to the ENTER/OK action.

You can set TOP MENU zone to open both the TOP and BOTTOM MENU at the same time via this menu:

TOP MENU → → Taps and Gestures → Activate Menu
CORNER TAP ZONES can be used for many different type of gestures including TAP, DOUBLE TAP, TWO FINGER TAP and TAP and HOLD.

PREVIOUS PAGE and NEXT PAGE zones can also be used for DOUBLE TAP gestures at the same time.

STATUS BAR zone can be tapped to cycle between STATUS BAR items if only one item is visible. If all items are visible, tapping will show and hide the STATUS BAR. Check “How can I configure the status bar ?” heading for more info.

File Browser
You will see FILE BROWSER when you run KOReader for the first time. You can access it from the reading screen by:
TOP MENU →
By default, FILE BROWSER shows your HOME which is your main library folder which you can change by tapping and holding on any folder. You can change its many options like how books are displayed or sorted via the TOP MENU by swiping down from the top part of the screen.

Circled items in the image are explained below:

RESET: This option basically resets your book by deleting its configuration file.

If you select this option, you will lose all your notes and highlights in this book.

OPEN WITH: KOReader has different engines for rendering different file types. In some cases you can open a file in a different engine to get some other features. See Viewing archive files and Viewing image files sections just below.

IGNORE COVER: If for some reason you want to disable the cover for this book (it may have wrong cover or cover is not very readable on the e-ink screen) you can select this.

IGNORE METADATA: If your book metadata is not correct, name field may show useless information. Select this option to show the file name instead of metadata.

REFRESH CACHED BOOK INFORMATION: KOReader caches a book's metadata and book cover when you add it to your library. If you make some changes to the book after copying to your device, this information might need to be updated. If you see wrong cover or metadata, you can refresh the book information with this menu item.

Viewing archive files
You can open ZIP, CBZ and EPUB (as they are ZIP archives too) files with the archive viewer to have a look at the contained files:
  1. In File Browser long-press the file name
  2. Tap Open with…
  3. Tap Archive viewer
Viewing image files
You can open image files with the image viewer instead of opening as a book. Files opened like this don’t show up in your history and have better scaling and rotation support.
  1. In File Browser long-press the file name
  2. Tap Open with…
  3. Tap Image viewer
Accessing your books
Following methods are available for accessing your books and articles:

You can assign gestures for each of these dialogs. For example while reading a book, you can access your History or Favorites with a gesture and open another book without going through the File Browser.

You can also set KOReader to start with Favorites or History screen via:

TOP MENU (in File Browser) → → Start with
User Interface Tips
KOReader’s interface and options change according to the file type you open. There are mainly two types of files: Fixed layout documents (PDF, DJVU, image files...) and Reflowable documents (EPUB, HTML, DOCX, RTF, TXT…).

- You can change the interface language via:

TOP MENU → → Language
- If you tap and hold an option or menu item (font weight, line spacing etc.), you can set its value as DEFAULT. The new value will only be applied to books opened from now on. Previously opened books will keep their settings. You can identify default values as a star (★) in the menu or as a black border around the indicators as seen below:

- On the BOTTOM MENU if you tap and hold an option’s name, you can see its explanation.

- You can CLOSE full screen dialogs (History, Table of Contents, Bookmarks, Reading Statistics etc.) by swiping down.

- You can take a screenshot by making a long diagonal swipe with your finger.

- In dialogs containing adjustment arrow buttons like the one above, you can tap and hold on arrow buttons to change the value in bigger increments.

You can CLOSE this type of dialog (non-full screen) by tapping outside of its window.

You can MOVE this type of dialog by holding its window title and dragging.

You can make this type of dialog SEMI-TRANSPARENT by tapping and holding the window title (when you want to see the text under it while adjusting a value).

KOReader supports dictionary lookup in EPUB and scanned PDF/DJVU documents. To see the dictionary definition or translation, just tap and hold a word.

- Tapping and holding a word brings up a dialog where you can also search the selection in the document for more occurrences or look it up on Wikipedia.

- If you want to change the size of user interface, there is a DPI setting for that:

TOP MENU → → Screen → Screen DPI

You can choose a value from the menu or select CUSTOM DPI to enter a value for fine tuning: Higher DPI = Bigger Interface

Note that there is also a Zoom (dpi) setting in the bottom bar. That one is related to the documents only. You can find the explanation in the next section.

- You can disable black flashing (automatic partial refresh to clear ghosting) of user interface if it disturbs you :

TOP MENU → → Screen → E-ink Settings
- If you want to check the current date you can tap on the clock in the TOP MENU.
Menu search
KOReader has lots of features so its menu system reflects this complexity. We have a Menu Search feature for finding menu items quickly. You can access it from:
TOP MENU → → Help → Menu search

Also you can assign this feature to a gesture or add it to your Quick Menu for faster access.

Scrolling types
KOReader has three types of touch scrolling. You can access this from:
TOP MENU → → Taps and Gestures → Scrolling
You have to enable Continuous mode from the Bottom menu to be able to use scrolling.

Classic scrolling: This mode works exactly like your phone/tablet scrolling.

Turbo scrolling: This mode allows you to scroll faster than classic scrolling. Also you can scroll several pages without lifting your finger. Scrolling amount is proportional to the distance you move your finger after you initiated scrolling.

On-release scrolling: This scrolling type is more suitable for e-ink screens. Because unlike other scrolling types, this mode doesn’t refresh your page continuously while scrolling. It works like classic scrolling but intermediate steps are not shown. So you scroll with your finger and when you release, page jumps to that position. This is especially useful to reposition and adjust the view if your book contains pictures or tables and you want to see all of it.

Go back to previous location
This useful feature works like the Back button in your browser. When you jump to some other part of the book using Skim widget, Bookmarks list, Book map etc. KOReader remembers your previous location. This is useful for example if you follow an internal link or reference. With one tap you can go back to where you come from. You can access this feature from:
TOP MENU → → Go back to previous location
Also you can go forward too, from the same menu. This feature is assigned to ← → multiswipe gesture. You can assign this to another gesture if you want (like tapping a corner) or add it to your Quick Menu.
Prevent flashing on pages with images
KOReader normally perform a full refresh on pages containing images (which you can observe as a black flash). The reason is to get rid of the residue and ghosting from the previous page. But this might not be necessary depending on your device and personal preferences. You can disable this auto-refresh behavior here:
TOP MENU → → Screen → E-ink Settings → Full refresh rate → Always flash on pages with images
Partial rendering support
With the version 2023.03, KOReader gained partial rendering capability while reading EPUB documents. Before this version, when you made an adjustment like changing font size, the whole book had to be rendered again to be able to preview the new setting. Depending on the device and book size, this can take a while to calculate.

With this new feature, when reading EPUB documents, text appearance adjustments can be done much quicker by only rendering the current chapter.

This is only possible if your EPUB is composed of multiple fragments. EPUB files are basically .zip archives that contain .html files. Some books can be a single .html file while others may be composed of multiple .html files like each chapter of the book is a seperate .html file. If your book is only a single .html file, partial rendering can not work, because for each change KOReader still has to calculate the whole book.

Also rotating your screen orientation is now much faster thanks to this feature. This feature is ENABLED by default. If necessary, it can be disabled per book (with a tap), or globally (with a long-tap) on:

TOP MENU → → Document → Enable partial renderings

After these partial renderings, KOReader and the book enter a degraded state: You can turn pages but some info and features may be broken or disabled (i.e. footer info, ToC, statistics…). To get back to a normal working state, KOReader has to render the rest of the book too. While this is happening, an icon at the top left corner of the screen indicates the status:

  1. Document is partially rendered. Page count, footer info and many things are innacurate. You can see how the new settings look and adjust further. You can also turn pages, jump links in this state.
  2. A full rendering is happening in the background. You can still turn pages, jump links, change settings.
  3. Full rendering is done, but not yet applied because KOReader is waiting for you to be idle to reload the rest of the book (idle=not interacting with the device). You can still turn pages, jump links, change settings.
  4. You've been idle for a while so KOReader is now reloading the whole document. At this step KOReader is blocked to prevent interaction.
When these icons are all gone, you are again in a fully working state. Generally this whole process is quick and as a user you don’t need to do anything extra. You can just adjust your settings and continue reading your book, KOReader will do the rest.
Bottom Menu Items Explained
You can see an explanation of these items when you long tap on their names in the bottom menu.
VIEW MODE: If you change to CONTINUOUS mode you can scroll the document like a web page. This mode is more suitable for non e-ink screen types (LCD, OLED). In continuous mode you lose TOP and BOTTOM MARGINS so text may be cut on first and last line of screen. To solve this problem you can enable PAGE OVERLAP:
TOP MENU → → Page Overlap
RENDER MODE: This option determines how your document is rendered by KOReader. Default is WEB and generally you don’t need to change this setting. When a book (or saved web page) is very complicated (specified widths or margins, negative margins, floats etc.) and layout looks bad or overflow the screen, you can try other rendering modes.

ZOOM (dpi): This setting can be thought of as a general zoom factor for the document (except font size). At 96 dpi (which is the default setting), images in the document are rendered at their original dimensions. Basically you will use this setting if you want to make images bigger without making the text bigger.

WORD SPACING and WORD EXPANSION: These two settings are related and they determine how your text will look when it is justified. When you justify text, space is added between words so that both edges of each line are aligned with both margins. Since word counts of lines are not equal all the time, in justified alignment, text has to be compressed or expanded to fill the line.

WORD SPACING: How much the SPACE characters in a line of text can be compressed to fit more words. This setting doesn’t affect words, it only changes the space between them.

WORD EXPANSION: If you have too much white space in a line, how much of that can be distributed into the words by expanding them. This setting affects the appearance of words. If you don’t want your words to expand, set this to NONE.

You can experiment with different settings until the text looks pleasing to you, then set them as defaults via their respective dialogs.

CONTRAST and FONT WEIGHT are two options that you can use to make your text bolder (or lighter). You can achieve the same appearance with either of these options but they use different methods to achieve it. Of course you can use them both at the same time. The differences between them can be summarized as:
CONTRAST

+ Doesn’t change font width, book length stays the same

+ Doesn’t need to re-render document, faster

- Might look bad on LCD or low DPI screens

FONT WEIGHT

+ Will use proper weighted fonts if you have them installed

+ Looks better on LCD or low DPI screens

- Has to re-render fonts, slower

FONT HINTING adjusts your text for maximum readability according to your screen’s pixel grid. NATIVE uses font’s internal hinting instructions, AUTO uses FreeType’s hinting algorithm. AUTO is a safer choice because font files that you installed may have problematic hinting instructions. Also AUTO handles CJK text better. You can try different settings to see which one looks better on your device.

FONT KERNING adjusts the spacing between letters to achieve a visually pleasing result. Default is BEST, which might be slower when opening files (depending on your device) but has better support for ligatures (see picture below for an example), joined Arabic glyphs and some other scripts. If your device is slow, you can try GOOD which is faster and may still look correct with western latin-script text.

ALT STATUS BAR enables an alternative status bar which is available only in reflowable documents (EPUB, HTML, DOCX, RTF, TXT…). After enabling it here, you can configure ALT STATUS BAR via:
TOP MENU → → Status Bar → Alt status bar
EMBEDDED STYLE and EMBEDDED FONTS determine if publisher’s styles and fonts embedded in the document will be used (or ignored) to render the document. These are general on/off switches. You can achieve more fine tuned tweaks for your document via:
TOP MENU → → Style Tweaks
IMAGE SCALING determines how images in your document are rendered. BEST looks more pleasing but it is slower.
Saving your text appearance settings for later use
This powerful feature allows you to save all the BOTTOM MENU settings + font type as a profile. This means you can have different group of settings for different conditions or book types which you can apply at once instead of changing the settings manually every time. For example you can create a: After adjusting your settings to your liking, you can create a profile from them via:
TOP MENU → → Profiles → New with current document settings
After creating a profile with your settings, you have many options for applying it to another book:

Please see the GESTURES, QUICK MENU AND PROFILES chapter for more information.

BASIC READING INFO
How can I personalize my text ?
*Font selection and style tweaks are available only on reflowable documents (EPUB, HTML, DOCX, RTF, TXT…). Fixed-layout documents like PDF/DJVU are not supported.

You can also change other formatting options from the BOTTOM MENU to fine tune the appearance of your text.

You can see your reading statistics via:

TOP MENU → → Reading Statistics
How can I control the backlight / frontlight of my screen ?
You can control your screen light via this menu. If you have warm lighting (normal white LEDs+orange ones) you can control them separately from this dialog. You can also define a gesture for this dialog:
TOP MENU → → Frontlight
How can I configure the status bar ?
You can configure bottom status bar from this menu. Feel free to explore the SETTINGS sub-menu to customize your status bar as you like.
TOP MENU → → Status Bar
There are many items you can show on the status bar. But by default, only one is shown at a time and you have to click on the status bar to cycle between them. If you want to show all items at once, enable this menu item:
TOP MENU → → Status Bar → Settings → Show all at once
You can sort the items via:
TOP MENU → → Status Bar → Settings → Sort items
You can toggle the visibility of the status bar with a gesture or via Quick Menu:
Gesture selection menu → Reader → Toggle status bar
There is also an ALT STATUS BAR which is available in reflowable documents (epub, html, docx, rtf, txt…). If you prefer to use this, you can enable via:
BOTTOM MENU → → Alt Status Bar
How can I change the screen displayed while sleeping ?
You can choose a book cover or a custom image as screensaver via this menu:
TOP MENU → → Screen → Screensaver

You can use JPG/PNG files as screensaver (properly dithered grayscale images look best). Transfer the files from your computer into any folder on your device. And choose this folder as your screensaver folder via this menu:

TOP MENU → → Screen → Screensaver → Settings
Please refer to this forum post for advanced information about screensaver images: https://www.mobileread.com/forums/showpost.php?p=3728291&postcount=17
Keyboard Usage And Tips
Entering extra characters
Koreader keyboard allows entering extra characters when you tap and hold a key. Most frequently used extra characters are shown below. You can tap and hold the key in the gray box to get the surrounding characters: Additionally there are some shortcuts for easier text manipulation. You can tap and hold these keys for the actions: For more information you can check the related wiki page:

https://github.com/koreader/koreader/wiki/Virtual-keyboard

KOReader also integrates the Chinese stroke keyboard for inputting simplified and traditional Chinese characters. You can find more info about it in our wiki:

https://github.com/koreader/koreader/wiki/Chinese-keyboard

Auto Warmth And Night Mode
This plugin allows you to adjust frontlight warmth in devices with natural (yellow/orange) light and set Night Mode (inverted screen colors – white text on black background) automatically according to a schedule. It can control them both or you can choose only warmth control or only Night Mode control mode, so you can adjust the other one manually.

This plugin comes enabled as default. If it is not in the menu, you can enable it via:

TOP MENU → → More tools → Auto Warmth and Night Mode
You can adjust the warmth of your screen frontlight automatically in two different ways:

FIXED SCHEDULE: In this mode your frontlight warmth changes according to the daily schedule you entered. This mode is STATIC, it doesn’t account for daylight length. The schedule stays the same all around the year.

SUN’S POSITION: This option calculates Sun’s position in your location according to COORDINATES and ALTITUDE information you entered. Frontlight warmth is adjusted gradually according to this calculated Sun position data. This mode is DYNAMIC. As the length of daylight changes around the year, plugin adjusts the schedule accordingly.

First have a look at this image to familiarize yourself with the terms used in the plugin:

Fixed Schedule Mode
  1. Go to the plugin menu:
    TOP MENU → → Screen → Auto Warmth and Night Mode
  2. Tap Activate menu item and then ACCORDING TO THE FIXED SCHEDULE
  3. Go back to previous menu and tap FIXED SCHEDULE SETTINGS menu item
  4. Set your warmth transition schedule by setting times for various items here. Refer to the image above for an explanation of items.
Sun’s Position Mode
  1. Go to the plugin menu:
    TOP MENU → → Screen → Auto Warmth and Night Mode
  2. Tap ACTIVATE menu item and then ACCORDING TO THE SUN’S POSITION
  3. Go back to previous menu and tap LOCATION SETTINGS menu item. Set your coordinates (necessary) and altitude (optional) correctly and give a name to your location.
  4. Go back to previous menu and tap WARMTH AND NIGHT MODE SETTINGS menu item
  5. Set your warmth transition schedule by setting times for various items here. Refer to the image above for an explanation of items.

You can see your current schedule via CURRENTLY ACTIVE PARAMETERS menu option.

Night Mode
While setting the warm light percentages for different intervals, you can also set that interval to Night Mode, which inverts the screen colors when that interval starts. If your minimum frontlight is still too bright or if you prefer a dark page background, you can activate this feature. To enable this, in the dialog on the right, you can tap Use night mode.

When you do this, warm light percentage will increase to 110% indicating that this interval has Night Mode activated. You will see a moon icon in the menu next to this interval. To disable Night Mode you can decrease the percentage to any value under 110.

If you want to manage Night Mode manually (or the reverse) you can change the working mode of this plugin by tapping on the option shown below.

Frontlight auto on/off
This feature turns your frontlight on at sunset and turns it off at sunrise according to your Currently active parameters in this plugin. You can override this change by manually turning your frontlight on/off. On the next sunrise/sunset, AutoWarmth will toggle it again if it is necessary. You can activate it by selecting Frontlight off during the day menu item in this plugin.
Fonts
How can I add my own fonts ?
KOReader supports fonts in most widely used TrueType (.ttf) and OpenType formats (.otf). Font files with these extensions can be directly copied to /koreader/fonts/ folder on your device. Check the wiki for more info:

https://github.com/koreader/koreader/wiki/Fonts

When starting up, KOReader compiles the available fonts from the font metadata/info and classifies them according to family and weights. This means you can add different weights and variants of a font and KOReader will try to use the most suitable one. Since it takes font family information from metadata, font names are not important when copying to your device. Installed fonts will be available after restarting KOReader.

You can check the Google Fonts website to get free fonts: https://fonts.google.com

Previewing the fonts on your device

KOReader can generate a document with sample text rendered with all the fonts installed on your device. This allows you to quickly compare the look and features of the fonts like ligatures and character sets in non-Latin scripts like Greek, Hebrew or Chinese. You can access this feature via:

TOP MENU → → Font → Font settings → Generate font test document
Monospace font scale

If your book includes parts with Monospace fonts (like in programming books), Monospace font might look disproportional even if they are technically at the same size. This is caused by differing font metrics. If you want to fix this difference, KOReader has an option that allows you to adjust the relative Monospace font size.

TOP MENU → → Font → Font settings → Monospace fonts scaling

Here you can increase or decrease the size of your Monospace font by adjusting its scaling as a percentage of the default size.

Using different fonts in one document

In HTML/CSS based documents like EPUBs, books can specify to use fonts by family instead of a specific font name. These families can be Serif, Sans-Serif, Monospace, Cursive, Fantasy, Emoji, Fang Song and Math. For example in a book, normal text can be shown in Sans-serif while dialogues are shown in Serif font. KOReader normally uses your default font for all these families except Monospace and Math (which is determined by the style of the text nodes, for example 'font-family: serif'). If you want these families to look distinct, you can assign specific fonts for them here:

TOP MENU → → Font → Font-family fonts

To change a family font for the current book just tap on the desired font name. If you want to set this for all your books, long-tap to set it as a Default (★). If a book abuses this font family feature to the point where your default font is hardly used, you can disable that family font for this book by unchecking the association.

MOVING THROUGH YOUR BOOK
There are many different ways of moving through your document in KOReader.

You can use the SKIM WIDGET, BOOK MAP or PAGE BROWSER features.

Skim Widget
You can also open this widget with a long-tap on the Status Bar in addition to:
TOP MENU → → Skim document
Chapter Marks
KOReader can show chapter boundaries from your documents on the SKIM WIDGET and PROGRESS BAR.

If your document has too many heading levels, your chapter marks can look crowded like the example on the left. You can change the depth of visible ToC mark levels via:

TOP MENU → → Settings → Progress Bars

You can also use this reduced ToC for:

If your document doesn’t have a Table of Contents, you can enable ALTERNATIVE TABLE OF CONTENTS. When this setting is enabled, KOReader will build a ToC from document headings (if available) or from individual HTML files in the EPUB. Long-tap the menu item for extra info:

TOP MENU → → Settings → Alternative table of contents
Book Map
Book map is a powerful and unique feature of KOReader which can be very useful for getting an overview of a book. For example if you are reading a book non-linearly by skipping some parts to read them later, it would be hard to track your progress. Book Map can show you which parts of the book you have already read, at a glance.

Additionally you can:

You can access Book Map via menu and you can also assign a gesture for quicker access:
TOP MENU → → Book map
User Interface And Controls
When you open the Book Map first time while reading a book, it will be in Grid View mode, fitting all chapters on a single screen to give the best initial overview of the book’s content. To get a detailed information about usage, tap the info icon at the upper left corner. You can close the Book Map by clicking X on the upper right corner or with any multiswipe gesture (UP-DOWN, LEFT-RIGHT etc.). You can customize Book Map by changing these options:

- First try swiping LEFT and RIGHT along the bottom edge of the screen to change width of columns indicating pages and observe how it changes the scale of map

- Then try swiping UP and DOWN along the left edge of the screen to change chapter title depth and switch to the Flat View. See examples below.

In addition to default Grid View above, here you can see the Flat View on the left and Grid View without chapter titles on the right. Note the changing left vertical scrollbar between views. If you want to switch back to the default view, you can long-press the info icon at the upper left corner.

Book map options
When you tap the menu icon on the Book map screen you are presented with the menu above. Menu options are explained below:
Page Browser
Page Browser can be used to navigate between pages like in a photo album by showing thumbnails of the pages as a grid. You can open Page Browser by tapping on the Book Map or from the menu. You can also assign a gesture for quick access.
TOP MENU → → Page browser
You can change the number of pages shown by swiping along the TOP and LEFT sides of screen. Icons on the bottom are the same as Book Map. Actually the bottom part is a linear version of the Book Map.
BOOKMARKS, HIGHLIGHTING AND NOTES
KOReader gives you options to interact with your book like you can do with a real book:

Bookmarks: You can add (and remove) a bookmark by pressing the upper right corner. This is the equivalent of folding the corner of a page on a real book and shows a similar icon when you enable it.

Highlights: You can highlight text in 4 different styles. In the image below, you can see a normal paragraph followed by different styles of highlights. Lighten (with gray background), Underline, Strikeout and Invert.

You can use all these styles at the same time, like they are different colored highlight markers. Or you can decide your favorite style and set it as default from this menu by long pressing:

TOP MENU → → Highlight style
Notes: You can also add notes to your highlights. Just tap on a highlight and choose Add note from the popup menu. You can also choose a Note marker that shows which highlights contain a note. There are three styles: Underline, Side line and Side mark (which is the pencil icon shown on the right side of the picture below): To enable this feature and choose a Note marker style, go to:
TOP MENU → → Highlight style → Note marker
How to highlight
KOReader has two highlighting modes for different use cases:

Normal mode is similar to selecting a text with your finger on a phone/tablet and more suitable if your highlights are shorter than one page.

Select and highlight mode is more suitable for highlighting longer passages which cross page boundaries. It might also work better if you have touch screen sensitivity problems or motor control issues with your hands. Because in this highlight mode you don’t need to drag your finger along the screen.

Normal mode
This mode is similar to selecting a text with your finger on a phone/tablet.
  1. Long-press on the starting word
  2. Move your finger to the end of the passage
  3. Release finger
If you reach page boundaries, KOReader will turn the page for you to continue highlighting (only in EPUB/HTML documents).
Select and highlight mode
If you have dictionary lookup enabled when long pressing a word, you have to drag your finger to initiate this mode.
TOP MENU → → Taps and gestures → Long-press on text → Dictionary on single word selection
  1. Long-press (or drag if dictionary lookup is enabled as described above) on the starting word, popup menu will show up.
  2. Tap on Select, now you are in highlighting mode. When you are in this mode, you will see an indicator at the upper left corner of the screen (which you can tap on it to get more information). You can cancel highlighting by tapping on the beginning of highlight again. You can turn pages with taps/swipes and freely navigate the document (TOC, skim etc) in this mode.
  3. Long-press (or drag if dictionary lookup is enabled as described above) on the ending word for your highlight, menu will show up again.
  4. Tap Highlight this time to finish highlighting the passage.
There is a faster method for this mode if you don’t need long-press menu items shown above. You can disable the popup menu completely so when you long-press on a word you will immediately enter the Select and highlight mode. This method is much faster and you can highlight any length of text with just two taps. To use this method enable this option:
TOP MENU → → Taps and gestures → Long-press on text → Select and highlight
KOReader can highlight a passage in different styles. If you use Lighten option, text background will be gray. Due to e-ink limitations, screens can’t change from white to gray directly, so highlighted part first has to turn black and then gray. If you want to avoid this flashing, you can choose Inverted as your highlight style. In this mode text background will be black so it can be set without flashing. You can adjust these highlighting options via:
TOP MENU → → Highlight style
You can add multiple highlights and notes to the same section of text. If they are overlapping, when you tap on a highlight you will be presented with a menu to choose which highlight you want to edit.
Selecting punctuation
When you are highlighting, KOReader tries to include the related punctuation marks around your selection. For example if you highlight from the first word to the last word of a sentence, KOReader will automatically include the punctuation marks at the both ends of the sentence to your highlight.

But if you start highlighting from the middle of a sentence, period at the end will not be included because KOReader assumes that you want to make a partial highlight. So if you want the punctuation marks to be added to your highlight, be sure that you select the whole sentence. Also you can add these marks later by long pressing the Highlight edit buttons.

Editing a highlight
When you click on an already highlighted text (without a note), you will see this popup menu. Delete and Add note items are clear. Bottom row menu items are used to extend or shrink the highlight. When you click on an already highlighted text with a note added, you will see this popup menu. Tap on Edit highlight to open the menu above where you can edit both the highlight and the contained note:

On your Bookmarks page you can filter the view to see only one type of bookmark by pressing the menu icon ( ) You can also filter by highlight style:

Exporting your highlights
After finishing a book, you can move it to a specific folder for archiving or processing purposes. Enable Move to archive plugin and set your target directory in the plugin’s settings (Set archive folder). After this, you can move a book to your archive folder using:
  • Move to archive plugin menu
  • With a gesture or
  • With a Quick Menu entry
KOReader provides different ways of exporting your highlights and notes from your reader device:
1. Export Highlights plugin
This versatile plugin can export your highlights to local files or online services.

Local export: You can export your highlights to your device in these file formats:

  • Text (.txt)
  • HTML (.html)
  • Markdown (.md)
  • Kindle Clippings (.txt)
  • JSON (.json)
You can choose your preferred export formats from:
TOP MENU → → Export Highlights → Choose formats and services
You can see the export location (and also change it if you want):
TOP MENU → → Export Highlights → Choose export folder

Online services: You can also export to these services over the network:

You have to enter your credentials for these services to be able to activate them.

You can find setup instructions for Joplin here: https://github.com/koreader/koreader/wiki/joplin

After selecting your formats, you can export the notes for the current book or all the books in your library from the same plugin menu.

If you want to export only some of the books in your library, you can do this from the File Browser:

  1. Select multiple books in the File Browser
  2. Tap on the menu button (shown as a check mark) at the top right corner
  3. Select Export highlights from the menu shown
2. Using KoHighlights
KoHighlights is an external program that you can install on your computer. It can access your book notes and highlights when you plug your reader to your computer. Check the project page for download and instructions:

https://github.com/noembryo/KoHighlights

3. Using Calibre
Calibre is an external program that you can install on your computer. You can import highlights into your Calibre database with its KOReader Sync plugin. You can install the mentioned plugin within the Calibre application. Check the project page for download and instructions:

https://calibre-ebook.com/

When you open a document in KOReader, it creates a directory alongside the document with same name as the document. This directory contains a .LUA file which includes all the highlights, notes and user options (formatting properties etc.) related to that document. You can manually backup/restore these directories.
READING PDFS
Reading large PDFs on a small screen
KOReader provides you many ways to read a PDF/DJVU document which is optimized for bigger (generally it is A4 or Letter) page sizes on your smaller screen device:

1. You can enable REFLOW

BOTTOM MENU → → Reflow

Reflow tries to extract the text portion from your document (if it is available) and format it as a single column. Results are generally satisfactory. You can also set this as DEFAULT by tapping and holding on it.

2. You can enable ZOOM TO CONTENT
BOTTOM MENU → →

With this option KOReader tries to crop margins from your document so text may look bigger on your screen. You can set FIT to WIDTH in the same menu which will try to fit only page width instead of whole page, so your text will look bigger.

3. You can try to use your device in LANDSCAPE orientation

This will make your screen wider so your document may look big enough to read comfortably.

BOTTOM MENU →
4. You can see your document at full size and scroll the screen to read different parts

This is especially helpful with comic books. First enable COLUMN MODE from this menu item:

BOTTOM MENU → →

Then select an appropriate flow direction for your document from the same menu:

- For example if you are reading an article which has two columns, you will scroll down until the end of page reading left column then go to right upper side to continue reading right column:

- Or if you are reading a comic book, you will want to go “right → down left → right” in a zigzag pattern: - For a Japanese comic book (right-to-left panel order) this might be the reverse:

In this mode you can also adjust Horizontal/Vertical Overlap and Number of Columns from the same menu to fit the text on your screen better. Feel free to experiment with settings.

Explanations Of Pdf Specific Bottom Menu Items

CONTRAST This setting adjusts black levels in your document. Be aware that same contrast value applies to both text and images in your document. If you set it very high, your images may become too dark to be readable.

DEWATERMARK Removes watermarks from the rendered document. It can also be used to remove gray backgrounds. This feature can convert a grayscale or color document to black & white to produce more contrast for easier reading.

RENDER QUALITY (REFLOW MODE) Sets the quality of text and image extraction processing and output. HIGH is more pleasing but it can be much slower (several seconds for page turn) than DEFAULT depending on your document. If your PDF/DJVU files are slow, this is the first setting you should check.

DOCUMENT LANGUAGE Sets the language to be used by the OCR engine.

FORCED OCR Force the use of OCR even if the document has a text layer

WRITING DIRECTION (REFLOW MODE) Text direction of original document. Set to RTL for languages like Arabic and Hebrew.

DOCUMENT COLUMNS (REFLOW MODE) Number of text columns in the original document.

AUTO STRAIGHTEN feature can straighten the pages of a problematic document, for example pages of a PDF which are scanned with an angle. It is available in PDF, DJVU, CBZ/CBT documents and image files. To enable, choose the maximum tilt angle which KOReader will try to correct. If it doesn’t correct you might have to choose a bigger angle. Note that this feature might slow down your reader depending on several factors.
OCR (Optical Character Recognition)
OCR (Optical Character Recognition) is the process of extracting text from images into machine readable format. In KOReader context, it is generally used for extracting text from scanned book pages in PDF files. KOReader relies on Tesseract Open Source OCR Engine for this task (https://github.com/tesseract-ocr/tessdoc).

In order to use this feature you need to:

  1. Install Tesseract language data to your KOReader
  2. Add newly installed languages to koreader/defaults.lua configuration file (necessary only if your language is other than English or Chinese)
Buttons on OCR menu will not function until you install the necessary Tesseract files. Details of this process can be read in the related wiki page: https://github.com/koreader/koreader/wiki/Dictionary-support#dictionary-lookups-in-scanned-pages
Panel Zoom (manga/comic)
This feature makes reading comic books easier on smaller screens. You can enable it while you are reading a PDF, DJVU, CBZ or CBT document via:
TOP MENU → → Panel Zoom (manga/comic)
When this option is enabled, KOReader tries to find the boundaries of rectangular panels on the screen. If you long-tap on a panel, KOReader zooms in to that panel. As you can guess, this feature works best with comics that has clean panel boundaries. Procedure can be seen below:

If you want to use this feature with other file types like EPUB, FB2, HTML or image files, you should open the file with a different engine: In the File Browser long-tap on the file name, tap Open with… and select MuPDF.

GESTURES AND KEYBOARD SHORTCUTS
There are many types of gestures you can use to control KOReader. Some gestures have limitations regarding where on the screen they can be used and which directions are supported. These limitations are indicated below.

Note that some devices support only single touch. So multi-finger gestures are not available on them.

TAP / DOUBLE TAP

Single or double tap with ONE finger

WORKS: Anywhere on the screen

TAP AND HOLD

Single tap and hold with ONE finger

WORKS: Only on four corners

TWO FINGER TAP

Single tap with TWO fingers at the same time

WORKS: Only on four corners

SPREAD AND PINCH

Same gesture as zooming in and out on a mobile phone, tablet etc.

WORKS: Anywhere on the screen

This gesture may work less reliably depending on your device. If that’s the case please choose another gesture type.

ONE FINGER SWIPE

Swiping motion with ONE finger

WORKS: Screen edges (HORIZONTAL and VERTICAL) Anywhere except edges (DIAGONAL)

TWO FINGER SWIPE

Swiping motion with TWO fingers at the same time

WORKS: Anywhere on the screen

MULTISWIPE

More than one swipe done after each other without lifting your finger. For example like drawing the letter U (DOWN-RIGHT-UP)

WORKS: Anywhere on the screen



Icons by Econceptive from the Noun Project

Predefined Gestures
This table shows the gestures available when you install KOReader for the first time. You can change these gestures according to your preferences via:
TOP MENU → → Gesture Manager
TAP CORNER
  • Top Left Corner > Toggle page flipping
  • Top Right Corner > Toggle bookmark
DOUBLE TAP
  • Left Side > Go -10 pages
  • Right Side > Go +10 pages
ONE FINGER SWIPE
  • Short diagonal swipe > Full screen refresh
  • Long diagonal swipe > Take screenshot
MULTISWIPE
  • ← → - Back to previous location
  • → ← - Go to latest bookmark
  • ↓ ↑ - Skim document
  • ↑ ← - Bookmarks
  • ↑ → - Table of contents
  • ↓ ← - Show frontlight dialog
  • ↓ → - Toggle reflow
  • → ↑ - History
  • ← ↑ - Book status
  • → ↓ - Go to page
  • ← ↓ - Back
  • ↑ ↓ ↑ - Previous chapter
  • ↓ ↑ ↓ - Next chapter
  • ← → ← - Open previous document
  • → ← → - Favorites
Gesture Categories
This is a list of every action that you can assign to a gesture using the Gesture Manager menu. You can use the search function of your browser (generally Ctrl+F) to search for an action here. These actions can also be used in your own Quick Menu. Please check the relevant section in the guide for more info.
General
  • Reading progress
  • Open previous document
  • History
  • Favorites
  • File browser
  • Dictionary lookup
  • Wikipedia lookup
  • Fulltext search
  • File search
  • Show menu
  • Menu search
  • Screenshot
  • Show ephemeris
  • Calibre metadata search
  • Browse all calibre tags
  • Browse all calibre series
  • Browse all calibre authors
  • Browse all calibre titles
  • (Execute) Profile x
  • Statistics calendar view
  • Statistics today’s timeline
  • Open vocabulary builder
Device
  • Exit screensaver
  • Exit KOReader
  • Restart KOReader
  • Toggle hold corners
  • Toggle touch input
  • Rotation
  • Toggle orientation
  • Invert rotation
  • Rotate by 90 CW
  • Rotate by 90 CCW
  • Toggle Fullscreen
  • Show network info
  • System statistics
Screen and lights
  • Toggle night mode
  • Set night mode
  • Full screen refresh
  • Auto warmth off
  • Auto warmth cycle through modes
Reader
  • Open next document in folder
  • Show bottom menu
  • Toggle status bar
  • Previous chapter
  • Next chapter
  • First page
  • Last page
  • Turn pages
  • Go to page
  • Skim document
  • Previous bookmark
  • Next bookmark
  • Go to latest bookmark
  • Back
  • Back to previous location
  • Forward to next location
  • Follow nearest link
  • Follow nearest internal link
  • Add current location to history
  • Clear location history
  • Table of contents
  • Book map
  • Book map (overview)
  • Page browser
  • Bookmarks
  • Bookmark search
  • Book status
  • Book information
  • Book description
  • Book cover
  • Translate current page
  • Toggle bookmark
  • Toggle page turn direction
  • Invert page turn buttons
  • Set highlight action
  • Cycle highlight action
  • Cycle highlight style
  • Save book metadata
  • Move current book to archive
  • Book statistics
  • Synchronize book statistics
File browser
  • Folder up
  • Show plus menu
  • Toggle select mode
  • Refresh content
  • Folder shortcuts
  • Go to page
  • Back
Reflowable documents
  • Set font
  • Increase font size
  • Decrease font size
  • Set font size
  • Word spacing
  • Word expansion
  • Contrast
  • Font weight
  • Font hinting
  • Font kerning
  • Two columns
  • L/R margins
  • Sync T/B margins
  • Top margin
  • Bottom margin
  • View mode (page-continuous)
  • Render mode
  • Zoom
  • Line spacing
  • Alt status bar
  • Embedded style
  • Embedded fonts
  • Image scaling
  • Invert images
Fixed layout documents
  • Toggle page flipping
  • Toggle bookmark flipping
  • Toggle reflow
  • Zoom mode
  • Change zoom factor
  • Toggle panel zoom
  • Page crop
  • Margin
  • Horizontal overlap
  • Vertical overlap
  • Fit
  • Zoom factor
  • Zoom to
  • Direction
  • View mode
  • Page gap
  • Progress bar
  • Line spacing
  • Alignment
  • Font size (set)
  • Font size (inc/dec)
  • Word gap
  • Reflow
  • Contrast
  • Dewatermark
  • Render quality
  • Document language
  • Forced OCR
  • Writing direction
  • Auto straighten
  • Document columns
Keyboard Shortcuts
If you are using the desktop Linux version of KOReader, you can use keyboard shortcuts for navigating the user interface. These can also be used with non-touch devices which has a keyboard, like Kindle 3, Kindle DX, Android and Android TV.
File browser mode
  • Open top menu - F1
  • Navigate to home - Home
  • Navigate file list - Up/Down
  • Open selected book - Enter
  • Show selected book’s context menu - Right
  • Exit application - Esc
Reading mode
  • Open selected page link / Open bottom menu - Enter
  • Open top menu - F1
  • Back/exit application - Esc
  • Show bookmarks - B
  • Show TOC menu - T
Highlighting
  • Enter highlighting mode - H
  • Start/stop highlight selection - Enter
  • Move highlight indicator - Left/Right/Up/Down
  • Move highlight indicator faster - Shift+Left/Right/Up/Down
  • Exit highlight mode - Esc
Fonts
(Not available for PDF, DJVU and images.)
  • Show font menu - F
  • Increase font size - Shift+Page Up
  • Decrease font size - Shift+Page Down
Links
  • Select next page link - Tab
  • Select previous page link - Shift+Tab
Image viewer
  • Zoom in - Page Down
  • Zoom out - Page Up
Navigating the book
  • Next/previous page/view - Left-Right / Up-Down / Page Up-Page Down
  • Go to the beginning of book - 1
  • Go to 11% of book - 2
  • Go to 22% of book - 3
  • Go to 33% of book - 4
  • Go to 44% of book - 5
  • Go to 55% of book - 6
  • Go to 66% of book - 7
  • Go to 77% of book - 8
  • Go to 88% of book - 9
  • Go to the end of book - 0
In Skim Document dialog
  • Go to the beginning of book - Q
  • Go to 11% of book - W
  • Go to 22% of book - E
  • Go to 33% of book - R
  • Go to 44% of book - T
  • Go to 55% of book - Y
  • Go to 66% of book - U
  • Go to 77% of book - I
  • Go to 88% of book - O
  • Go to the end of book - P
Page zooming
(Only available for PDF, DJVU and images.)
  • Zoom in - Shift + PgUp
  • Zoom out - Shift + PgDown
  • Zoom to fit page - A
  • Zoom to fit page width - S
  • Zoom to fit page height - D
  • Zoom to fit content - Shift+A
  • Zoom to fit content width - Shift+S
  • Zoom to fit content height - Shift+D
  • Manual zoom mode - Shift+M
QUICK MENU AND PROFILES
Quick Menu
Quick Menu is a recent feature of KOReader which allows you to have a quickly accessible personalized menu. You can assign this menu to a gesture and access it with a single swipe. You can see an example menu on the right. You can even have a menu longer than your screen, it is scrollable.

Basically, any action you can assign a gesture can be added to the Quick Menu. Its advantages are:

  1. You don’t need to memorize lots of gestures for every action.
  2. Some infrequent actions may not worth a gesture but it can be too much hassle to find it in the menu system. You can add this kind of rarely used actions to this menu instead.
  3. If you are installing KOReader for a relative or friend, you can add their favorite actions to this menu so they don’t even need to go into the menu system while using KOReader.

An example Quick Menu:

There are two methods for creating a Quick Menu. Easy and Advanced. If you need only one menu, Easy method should be enough for you. If you want show different menus with different gestures you need to use Advanced method. Another advantage of Advanced method is that, if you want to use another gesture for your menu you can easily move it to another gesture. If you want to use another gesture while using the Easy method, you have to re-create your menu under the new gesture.

Easy method
  1. Go to Gesture Manager menu via:
    TOP MENU → → Taps and Gestures → Gesture Manager
  2. Decide a gesture for opening your menu and tap on it.
  3. Choose the actions you want to see in your menu from the gesture configuration menu. You can select many actions at once of course.
  4. After selecting all your actions, you will tell KOReader to treat this gesture as a menu. You achieve this by enabling Show as Quick Menu item on the second page as you can see in the picture below.
  5. You can sort your menu items with the Sort option just below it.

Now you can launch your menu with the gesture you selected. If you want to change the menu items, you can open the gesture page and add/remove items.

Advanced method
As we said above, if you are not planning to add more than one Quick Menu you don’t need this section.

Quick Menu is actually a Profile which appears on your screen as a menu. So first you have to learn about Profiles. If you already know how to use Profiles, you can continue reading, otherwise jump to the Profiles heading (next section), create a Profile with some items and come back here.

We assume that you already created a Profile as instructed in the previous paragraph. Now we will turn our Profile into a Quick Menu.

1. Go to your newly created Profile and enable Show in action list (shown in the image below). This will make your Profile visible in the Gesture Manager. Also enable Show as Quick Menu (also in the image below) so your profile will be shown as a menu instead of being silently executed.

2. Now we need a way to access our menu. Go to the Gesture Manager and choose a gesture from the list to assign to our menu. Let’s say we want to tap the corner of the screen to show menu. Now tap on Tap corner then choose Bottom left. Now tap on General and go to the second page. You will find your profile as Profile x where x is the name you gave to this Profile. Tap on its checkbox to assign your profile to this gesture.

After all the steps, now you should see your menu when you tap on the bottom left corner. You can edit your menu by going to its Profile page where you can add or remove items. Also there is a Sort item there so you can change the order of your menu items.

As we said, a Quick Menu is actually a Profile. Which means you can have more than one menu. You can create another Profile and follow the same steps to create another menu if you want.

Profiles
A profile is basically a collection of actions that can be triggered with a single tap (like a macro).

As an example, imagine that when reading some type of books, you always:

  • Rotate the screen to landscape orientation
  • Increase the font size and contrast and
  • Turn the screen light on

With the profiles plugin, you can do all these at once with a single action.

When you activate another profile, changes made in the first profile will not be reversed. For example, you activate a profile which sets your font size from 20 to 24. Then you activate another profile that adjusts your frontlight. Your font size stays at 24 after activating the second profile. Because profiles in KOReader doesn’t have an exit or reverse action.

To create a profile first be sure that Profiles plugin is activated. If you don’t see it under:

TOP MENU → → Profiles

then you have to turn it on from:

TOP MENU → → More tools → Plugin management
Creating a profile
In Profiles menu tap New and give a descriptive name for your profile. Now you should see your new profile in the menu. Tap on it and you will see the screen on the left side. You can also Delete, Rename or Duplicate a profile from this menu.

When you tap on Edit actions menu item you will see the menu on the right. This is the same menu as the gesture selection menu and there are actions in many categories. Which means you can perform any Gesture action using a Profile.

You can now select several items from all these categories. The actions you selected here will be performed when you activate this profile.

Activating a profile
There are many ways to activate a profile:
  1. You can activate a profile with a long press on its name from this same Profiles menu
  2. You can activate a profile using a gesture. For this, you have to enable Show in action list from the profile’s menu. Now you can select it via:
    TOP MENU → → Taps and gestures → Gesture manager → “ANY GESTURE” → General → Profile “Your profile name”
  3. You can also activate a profile automatically when KOReader starts if you enable Autostart in the Profile’s menu. Note that this is only possible when KOReader is starting with the File browser or Last file.
Technical details of Profiles and Quick Menu ADVANCED
In KOReader we have a set of actions/settings and this set can be created in two ways:
  1. As a profile (which is explained as the Advanced Method and stored in settings/profiles.lua)
  2. As a list of actions assigned to a gesture (which is explained as the Easy Method and stored in settings/gestures.lua)

This set can also be executed in two different ways:

  1. Applying each action in the (sorted) order when triggered (as a Profile)
  2. Showing it as a Quick Menu

Adding/removing actions of a set and enabling/sorting Quick Menu are done via the same actions menu. The only difference is that the actions menu in the Gesture manager has two more items (Pass through), that is why Show as Quick Menu and Sort items are on the second page.

PLUGINS AND USER PATCHES
Plugin types
Plugins are small programs that expand the capabilities of KOReader. You can think of them like browser add-ons. KOReader has 3 categories of plugins:
Internal
Internal plugins are part of the core program.
  • They are directly accessible from the KOReader plugins menu.
  • They don’t need installation. You can enable them from the menu.
  • They are checked by our developers so they are considered safe.
  • They are automatically updated when you update KOReader.

You can enable/disable them via:

TOP MENU → → More tools → Plugin management
Contrib ADVANCED
This group contains non-official plugins which are not part of the core logic of KOReader.
  • They have to be installed manually and then activated from the plugins menu.
  • They should be updated manually.
  • They are checked by our developers at the time they were added to our repository so they are considered safe.
You can access them from this page: https://github.com/koreader/contrib They can be installed by downloading the plugin’s directory from the page above and copying it under koreader/plugins folder on your device. But still check the plugin’s page for other possible instructions.
External ADVANCED
These are plugins that are developed independently from the KOReader team.
  • They have to be installed manually and then activated from the plugins menu.
  • They should be updated manually.
  • They are NOT checked by our developers so be aware that there might be risks using them.

Some notable examples of these external plugins:

Also you can click this link to open a search page on Github to discover more KOReader plugin projects: https://github.com/search?q=koplugin&type=repositories

List of internal plugins

Auto frontlight - Automatically toggles the frontlight according to ambient light level (Only available on Kindle Voyage and Oasis)

Auto warmth and night mode - Allows you to adjust frontlight warmth in devices with natural (yellow/orange) light and set Night Mode automatically according to a schedule

Auto power save - Puts the device into standby, suspend or power off after specified periods of inactivity

Autosuspend - Suspend device after chosen period of inactivity (available on all e-ink devices except android os)

Autoturn - Automatically turns the page after a set period of time

Background runner - Service to other plugins: Allows tasks to run regularly in the background.

Battery statistics - Collects and displays battery usage statistics of your device

Book shortcuts - Allows adding a book shortcut to a gesture

Calibre - You can send documents from your Calibre Library directly to your KOReader devices via WiFi connection. Check the wiki for how-to: https://github.com/koreader/koreader/wiki/Calibre-wireless-connection

Cover browser - Allows cover display modes for file browser and history

Cover image - Saves the cover image of the current book as a file (available on Android/PocketBook/reMarkable devices)

Export highlights - Export highlights and notes to local files or to Joplin (a note taking application)

Flashcard trainer - Show flashcards using spaced repetition (SM2) of highlight from your library

Gestures - Provide gesture support for KOReader

Japanese support - Japanese language support for KOReader that extends built-in dictionary and selection system

Keep alive - Keeps the device awake to prevent automatic WiFi disconnects

Move to archive - Moves current document to archive folder

News Downloader - Retrieves RSS and Atom news entries and saves them as HTML files. Check the wiki for how-to: https://github.com/koreader/koreader/wiki/News-downloader

OPDS - Allows you to download books from online catalogs

Perception expander - Allows using peripheral vision to read more quickly. Check this YouTube video to see how it works: How to Triple Your Reading Speed in 20 Minutes (Tim Ferriss)

Profiles - Allows combining multiple settings to make switchable profiles

Progress sync - Synchronize your reading progress across different KOReader devices. Check the wiki for how-to: https://github.com/koreader/koreader/wiki/Progress-sync

QR from clipboard - Generates a QR code from clipboard content

Read timer - A countdown timer to display a message after a user defined time

Reading statistics - Calculates reading sessions statistics and reading speed for use in chapter/book remaining time estimations

SSH - Allows access to your device over SSH protocol. You can access via FTP applications or even your file manager if it supports. Check the wiki page for how-to: https://github.com/koreader/koreader/wiki/SSH

System statistics - You can see your CPU/RAM/BATTERY info via this plugin under:

TOP MENU → → Help → System statistics

Terminal emulator - Starts a shell (command prompt) on your device that can run full terminal apps

Text editor - A basic text editor to create and edit plain text files

Time sync - Synchronizes the device time with NTP servers

Tweak document settings - Allows tweaking settings of a document before it is loaded based on external factors

Wallabag - Downloads the latest articles from a Wallabag server as individual EPUB files. Check the wiki page for more info: https://github.com/koreader/koreader/wiki/Wallabag

User patches ADVANCED
User patches are small files written in Lua language. They can change the functionality of KOReader without modifying your installation permanently. They can be written by developers, other users or you can write one yourself (if you have the necessary extensive knowledge about the KOReader internals).

You can find a current list of User patches in the related GitHub wiki page:

https://github.com/koreader/koreader/wiki/User-patches

and in the issues list under the User patch available tag:

https://github.com/koreader/koreader/issues?q=+label%3A%22User+patch+available%22

Basic usage – Adding an already written patch to your KOReader:

  1. Create a directory named patches under koreader directory on your device (On Android this folder is located on the SD-card)
  2. Download and put the patch file with .lua extension in this patches directory
  3. Restart KOReader

Patch manager

When you create a patches directory as instructed, a new plugin named Patch Management becomes available in the plugins menu after restarting KOReader. With this plugin you can see the list and status of your user patches and enable/disable them. You can tap About patch manager menu item to see more info.

Naming the patch

Execution order of a patch is determined by the first digit of the number in the patch name. For example: 2-TOC-title-patch.lua If there are several patches starting with the same digit, the execution order is the natural order (1<10<11<12<13<...<109<...<10010). If you are just downloading an already made patch you don’t need to change the file name.

Names starting with:

  • 0 - Executed very early and only once after an update
  • 1 - Excuted very early on every start of KOReader (but after 0 if applicable)
  • 2 - Executed after UIManager is ready on every start of KOReader
  • 3-7 - Reserved
  • 8 - Executed before exit and before settings get saved
  • 9 - Executed right before exit

If you have a problem with a user patch, you can revert to your previous configuration by removing the patch file.

PREPARING AND TRANSFERRING YOUR DOCUMENTS
Transferring books to your reader
KOReader supports PDF, EPUB, DJVU, MOBI, CBZ, CBT, DOCX, RTF, HTML, TXT, XPS, FB2, PDB, CHM and ZIP files.

KOReader can reflow PDF documents (this option can be found in the bottom menu while reading a fixed-layout document like PDF) to make them suitable for the small screens of e-readers. But for best results, you may want to convert your documents into more flexible EPUB format. You can use Calibre (https://calibre-ebook.com/) for all kinds of conversion between formats.

There are many ways to transfer your documents to your device. Note that you may need to restart KOReader to index the transferred documents (or refresh directory if you have Pocketbook/Android).

In addition to transferring files the same way you would with the built-in reader application, other options are available depending on your device:

  1. USB mass storage mode within KOReader: This mode is available for KOBO and some CERVANTES devices.
  2. Cloud storage (Dropbox/FTP/Webdav): To use this function you have to add accounts for a cloud storage server via menu shown below. Process is explained via INFO buttons while adding accounts:
    TOP MENU (in File Browser) → → Cloud storage
  3. SSH/SFTP access: KOReader can act like an SSH server, which you can access from a computer to transfer files (available on Kobo, Kindle, Cervantes). You can use an SFTP application (like Filezilla) or access via your file manager if your operating system supports. Check wiki for how-to: https://github.com/koreader/koreader/wiki/SSH
  4. Calibre transfer: With the Calibre plugin you can send documents from your Calibre Library directly to your KOReader devices via a wifi connection. Check wiki for how-to: https://github.com/koreader/koreader/wiki/Calibre-wireless-connection
  5. News downloader: With this plugin you can download RSS and Atom news entries as HTML files. Check wiki for how-to: https://github.com/koreader/koreader/wiki/News-downloader
  6. Wallabag: With this plugin you can retrieve articles from Wallabag, a server based read-it-later service like Pocket. Check wiki page for more info: https://github.com/koreader/koreader/wiki/Wallabag
Optimizing EPUB/PDF documents for your mobile reader device
Most widely used applications for converting or optimizing your document for your mobile reading device are Calibre (EPUB, Kindle focused) and K2pdfopt (PDF focused).

Calibre can convert your documents between many formats. It also has a built-in editor that allows you to edit e-books (and fix problems) in the most popular e-book formats, EPUB and Kindle. https://calibre-ebook.com/

K2pdfopt optimizes PDF/DJVU files for mobile e-readers and smartphones. It works well on multi-column PDF/DJVU files and can re-flow text even on scanned PDF files. It can also be used as a general PDF copying/cropping/re-sizing/OCR-ing manipulation tool. https://www.willus.com/k2pdfopt/

SingleFile is a browser extension for Mozilla Firefox, Google Chrome and Microsoft Edge. This extension allows saving a web page as a single .html file with all resources (images, stylesheets, scripts) embedded. https://github.com/gildas-lormeau/SingleFile#install

ZIP file support
KOReader can read files stored/compressed in ZIP files. A ZIP file can contain many types of documents like html, txt or images. KOReader can open your ZIP file properly if you give it a hint for the type of file in the ZIP archive. If you give your file only a .zip extension, KOReader will assume that this archive contains images and try to open it like a CBZ file.

DEFAULT CASE: yourfilename.zip - Assumed to be a zip file of images (and opened by MuPDF engine)

If your zip file contains one of these types (instead of just images), please name it accordingly:

  • FictionBook - yourfilename.fb2.zip
  • HTML - yourfilename.htm.zip / yourfilename.html.zip
  • Text log files - yourfilename.log.zip
  • Markdown - yourfilename.md.zip
  • Rich Text Format - yourfilename.rtf.zip
  • Plain text - yourfilename.txt.zip

If the documents are not named like this, the wrong reader/format engine is likely to be used and you will see the No reader engine for this file or invalid file message. You can rename this file as explained above or long-press the filename and then choose Open with... to select the correct engine.

Optimizing manga for your mobile reader device
If you like reading manga books on your e-ink device there are some tips that can make your experience better. Preparing your own manga files is the best solution if you're not satisfied with how comics look on your device.

File type

File types like MOBI and EPUB are not suitable for handling primarily image content (e.g., manga/comics). MOBI support in KOReader is minimal to nonexistent, and EPUB’s text rendering priorities can cause problems when showing full-page images (for further technical details: https://github.com/koreader/koreader/issues/9163#issuecomment-1146637205).

Your best option is building a CBZ file which works better in KOReader. A file with .cbz extension is a zip file (with no compression) that is a collection of images. It saves multiple images, commonly .png or .jpeg files, organized into pages of the comic. KOReader can also open CBT files, which are similar to CBZ files but use TAR archive format.

Easiest way to convert a manga to CBZ is to get the manga as images from various websites, then convert them using Kindle Comic Converter (https://github.com/ciromattia/kcc). There are some useful settings like auto-rotating two-page splits to landscape and applying dithering so that eink-rendered gradients are smoothly dithered without jagged layers.

Resolution

The best results can be achieved by resizing your images to exactly your e-reader screen size. A screen-specific CBZ which targets the exact screen size of the device, prevents rescaling during reading. KOReader downscales your images to your screen size while reading but this is not recommended because KOReader adds a dithering pass before scaling and this causes loss of quality.

But if you want to use your hand made CBZ on more than one device or you want to preserve high resolution for future proofing, your best option might be to make the CBZ for your highest resolution device. Or pick an arbitrary "high" resolution, possibly one that matches the source. 300 PPI or better (up to 450 or even 600), unless the source is lower of course. If we assume a screen size of 8", 1500×2000 is a good target resolution. For bigger images, you should try it on your device and see whether it can deal with it. Especially old Kindles with low memory can struggle with sizes like 3000×4000 for example. If you're automating the process, it might be worth considering creating both a lower and higher quality version (e.g., at 200/400 or 300/600 DPI).

KOReader doesn't parse spine page-progression-direction="rtl" attribute of the books. So it doesn’t change page turning direction even though the file was created with right-to-left reading. Users can switch this via:
TOP MENU → → Taps and gestures → Page turns → Invert page turn tap and swipes / buttons
Advanced preparation of manga
The following is an example procedure to process one manga file:
  • Download Kindle Comic Converter (KCC) from https://github.com/ciromattia/kcc
  • Download your manga from the source of your choosing (i.e. HakuNeko)
  • Unpack the manga file. Now you should have a directory that contains only images (or subdirectories with images, no archives)
  • Process this directory with KCC. Each directory will produce a single CBZ file, so if you want to make several volumes at once, select multiple directories at once

Some useful settings of KCC:

Spread splitter: This feature detects double pages and allows you to rotate or cut them in two.

Upscaling: Enlarge images that is smaller than your target resolution.

Immersive mode in KOReader
If you would like to enjoy your manga in a more immersive way, make sure that you selected the exact same resolution as your device’s screen resolution in KCC when creating your CBZ file. Also you can hide the bottom progress bar while reading your manga in KOReader. So you will have an immersive full screen view of your manga without obstructions.
Extra step for smooth gradients ADVANCED
After using KCC to create a CBZ file, you can apply additional dithering to the images. This way, eink-rendered gradients will be smoothly dithered without jagged layers. This step will produce fine-tuned manga volumes which look better in KOReader.

You can use ImageMagick to process your images. ImageMagick, is a powerful open-source software suite for displaying, creating, converting, modifying, and editing raster images. You can download ImageMagick and use it from the command line to process many images at once.

  1. Unpack the prepared CBZ file that you created with KCC,
  2. Download the following file (dither_pack.zip) which contains two batch files (.BAT) and a GIF color template: https://disk.yandex.com/d/glEebjmPYYp7og
  3. Extract these three files next to your images that will be processed
  4. Edit the _magick_manga_ditherN_resize.bat and change the resolution to your device resolution (in both places in the BAT file).

    Next step will replace all the images in the directory with the processed ones. So make sure that you have a copy of them in some other directory if you want to keep the originals.

  5. Run _magick_manga_ditherN_resize.bat to resize and dither the images.
  6. Assuming you have 7-Zip installed, run _batch_archive.bat to pack all the processed images into a CBZ archive.
Reversing the page turn direction for authentic Japanese manga ADVANCED
You can make KOReader turn pages from Left to Right, so that swipes and tap zones are swapped. To enable this, add the following lines to this file → /koreader/settings/directory_defaults.lua

["/storage/emulated/0/Books/manga"] = {
["inverse_reading_order"] = true,
["kopt_zoom_direction"] = 0,
},

where /storage/emulated/0/Books/manga is the absolute path to the directory containing your mangas. After this change, when you open a file from the mentioned directory, your swipes and tap zones will be swapped.

TIPS
Updating KOReader

KOReader can update itself over Wi-Fi. You can trigger the check via this menu item:

TOP MENU → → Update → Check for update
Automatic dimmer

KOReader can dim your frontlight to preserve battery if your device is idle for a while. You can turn on and adjust this feature via:

TOP MENU → → Screen → Automatic dimmer
Line/word count of a page

If you want to know how many lines or words are being shown on the current page you can see it at:

TOP MENU → → Book information
How can I add a password lock to KOReader?
We don't have a direct option for this in KOReader. But there is a workaround to achieve this kind of lock screen functionality. You can set up KOReader to keep the screensaver on the screen until you enter a chosen gesture. To achieve this:
  1. Choose any gesture (including the complex ones with custom multiswipes) and make it your "unlock" gesture by going to:
    TOP MENU → → Taps and gestures → Gesture manager → "your selected gesture" → Device → Exit screensaver
  2. And then enable this option:
    TOP MENU → → Screen → Screensaver → Settings → Keep the screensaver on screen after wakeup → Until 'Exit screensaver' gesture
Switching between documents quickly

If you need to switch between two documents (when comparing them for example), there is a quicker way than going through the File Browser. KOReader can open the last document with a gesture (←→← multiswipe). If you define a gesture’s action as Open previous document, you can switch between two documents quickly similar to Alt+Tab feature on the desktop computers. You can find this feature under:

TOP MENU → → Taps and gestures → Gesture manager → “ANY GESTURE” → General → Open Previous Document

Also you can use the History dialog to switch between documents quickly. The history screen can be opened with the →↑ multiswipe gesture. You can also define any other gesture for this of course.

Applying current defaults to an already opened book

When you adjust your document defaults like default line spacing or default contrast, this new value will only be used for the new documents you open after the change. Your already opened books will look the same. For example, if you change your default FONT, you will probably adjust FONT WEIGHT and LINE SPACING to more suitable values for this new font. Then probably you will want to apply these changes to all your opened books. With this feature you don’t need to change these values manually in all your opened books.

You can easily apply these changes to your already opened books by choosing:

TOP MENU → → Reset document settings to default

When you click this option, your current book will reset to latest defaults you set. Don’t worry, this will only change the appearance of the book. Your reading position, highlights, notes and bookmarks will be preserved.

Saving current book settings as defaults

When you adjust a book to your liking, for example by changing line spacing, font contrast etc. you can save all the changes at once as defaults. Then you can apply these settings to other books with the Reset document settings to default option as explained above.

You can save your changes as defaults by choosing:

TOP MENU → → Save document settings as default
Avoiding clicking links accidentally

If your document has links and you are accidentally clicking them while turning the page or using other gestures, you can turn off Following links by tapping via this menu item:

TOP MENU → → Taps and Gestures → Links → Tap to follow links

After disabling this setting, to follow a link you have to long-tap on it and select Follow link from the popup menu. If you have the opposite problem and you want to make tapping links easier, you can enable Allow larger tap area around links from the same menu.

Optimizing your battery life

Li-ion batteries experience more degradation at the extreme ends of their charge levels. To minimize this degradation and extend your battery life, you can limit your minimum discharge level to 20% and maximum charge level to 80% (as in electric vehicles and some newer phones). Which means you start charging your device when the battery goes down to 20% and unplug when it reaches 80% (or 25%-75% if you are extra cautious).

KOReader can warn you by showing an alert when charge level reaches your defined limits:

TOP MENU → → Device Status Alerts → Battery Level
Keeping an eye on your memory usage

In older Kindle devices some of our users reported crashes due to limited memory. KOReader memory usage can go up if you open many files in one session. Especially PDF’s increase this amount. You can add a memory indicator to your STATUS BAR and restart KOReader if this value gets high, to avoid crashes or reboots.

TOP MENU → → Status Bar → KOReader memory usage

Also you can configure KOReader to restart automatically if memory usage reaches a threshold via:

TOP MENU → → Device → Device Status Alerts
Checking your battery consumption details

You can see your detailed battery usage statistics via this menu item:

TOP MENU → → More Tools → Battery Statistics
Checking detailed device statistics

You can see your system information like CPU/DISK SPACE/RAM usage via this menu item:

TOP MENU → → Help → System statistics

Changing your book cover

You can change your book cover from this menu:

TOP MENU → → Book information → → Set cover image
Reading statistics after midnight

In reading statistics you can change the start of day used for calculations. This is useful if you are reading after midnight for example and want your reading session counted as today instead of the next day. This applies only to the Day timeline view and optionally to the Calendar view; it does not apply to any of the other statistics reports. You can set this time at:

TOP MENU → → Reading statistics → Settings → Daily timeline starts at...
TROUBLESHOOTING
My status bar disappeared

Probably you tapped on STATUS BAR touch zone (check USER INTERFACE section to see an overview of touch zones) and hide your status bar. You can bring it back by tapping the same zone. Check “How can I configure the status bar ?” section to see details.

Sometimes my taps are registered as a long tap or double taps

This can happen in cases like shaking hands or device touch screen problems. If you have this problem, you can try to increase the Tap interval. By increasing this interval, you tell KOReader to ignore quick taps at the same location.

TOP MENU → → Taps and Gestures → Gesture intervals → Tap interval

If your two consecutive taps are separated by a distance, this would not apply. So you can still quickly browse pages by tapping quickly alternatively with two fingers.

KOReader can't write to the SD card

In Android devices KOReader can’t write to the external storage due to Android system restrictions. If you want to change your screenshot saving location, be careful to choose your device’s internal storage.

My PDF/DJVU files are slow

If you set your RENDER QUALITY to HIGH text will be more pleasing but it can be much slower (several seconds for page turn) than DEFAULT depending on your document. If your PDF/DJVU files are slow, this is the first setting you should check.

BOTTOM MENU → → Render Quality
Ghosting and residue when turning pages

Even if KOReader is set to full refresh after every page, you may still see some ghosting/residue after turning pages. This is a limitation of e-ink screen technology and can be observed on the latest generation devices, especially while reading mixed content (text+images) documents. As a workaround, you can refresh one more time manually after turning the page to get rid of these artifacts if they bother you (short diagonal swipe gesture by default).

Sleep cover problems

Sleep covers generally use a magnet embedded in the cover which enables wake up and sleep events via triggering a sensor in your device. In some cases like misaligned magnets, weak magnets etc. this triggering can be problematic. If you are having problems with waking up your device with your cover, you can disable this feature via this menu:

TOP MENU → → Device → Ignore all sleep cover events
Text indentation problems

If you get miscentered titles, headings or separators, or unexpected text indentation, try switching the style for your document. epub.css to html5.css. This kind of problems happen because some publishers assume their books will only be read on web browser engine based readers, so they don't bother "resetting" the styles.

TOP MENU → → Style
- Default HTML/EPUB (epub.css) is our book-oriented stylesheet, with text-align: justify, text-indent on P. It is better for unstyled books, and might make styled books more readable. - You can try switching to HTML5 (html5.css) if your book has indentation problems as mentioned above. This style provides a base stylesheet like web browsers do when rendering: text-align: left, no text-indent on P, spacing between P. But it doesn’t look pretty when publishers hasn’t done any styling.

Cleaning your book cover cache database

KOReader keeps a cache of your book covers to be able to show them quicker. In normal conditions this cache doesn’t get too big. If you remove lots of books or rename directories, you may want to clean up your book cover cache database to reclaim some space. You can do it from this menu:

TOP MENU (in File Browser) → → Settings → Mosaic and detailed list settings → Book info cache management
Clearing file cache

When you are reading a PDF/DJVU document, KOReader keeps a cache of the last page you have read. So when you reopen the book, it will be faster. But this cache can grow big if you are using KOReader for a long time and reading many PDF/DJVU documents. These cache files are kept under your KOReader installation directory under the cache folder. To clear this cache and reclaim the space you can go to:

TOP MENU (in file browser) → → More tools → Developer options → Clear caches
Clear this cache only if you really need this space. If you have enough space, clearing the cache will not provide any benefit. Instead, it will degrade the performance because your reader will have to render those pages again.

Backing up your KOReader settings

In rare cases that you want to backup and restore your KOReader with all your settings, you can backup these folders and files under the KOReader installation directory. Then you can overwrite them after a clean installation to restore your settings:

Folders:
  • settings
  • styletweaks

Files:
  • data/cr3.ini
  • defaults.persistent.lua
  • history.lua
  • settings.reader.lua
  • Files under data/dict/ and /data/tessdata/ directories (if they exist)
Your individual book settings and highlights are kept in the same directory as your books in a folder with the same name as your book. You can backup these folders separately if you wish.
MORE INFO
How to reach us about problems or suggestions
KOReader uses GitHub as its project base. You can report problems or suggestions on our GitHub page. You just need a GitHub account which is free. Click this link to open our Issues page: https://github.com/koreader/koreader/issues

On the Issues page click the New Issue button. But before doing that, we suggest using the search bar to see if there is already an existing issue about the same topic. You can also check other opened issues to have an idea about the process.

When you click the New Issue button you will be presented with two options:

Click the appropriate one and follow the instructions on the page to report your problem or suggestion. If you are reporting a bug, verbose debug logs are very helpful to determine the problem. You can enable them via:

TOP MENU (in file browser) → → More tools → Developer options → Enable debug logging + verbose debug logging
You can also . . .

Find other KOReader users on MobileRead forums
https://www.mobileread.com/forums/forumdisplay.php?f=276


Reach us at Gitter chat
https://gitter.im/koreader/koreader


Support the project via Liberapay
https://liberapay.com/KOReader