Skip to content
Kobo database backup and parser: extracts notes, highlights, reading progress and more
Python Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

Kobuddy is a tool to backup Kobo Reader sqlite database and extract useful things from it.

It gives you access to books, annotations, progress events and more!

Tested on Kobo Aura One, however database format shouldn’t be different on other devices. I’ll happily accept PRs if you find any issues or want to help with reverse engineering more events.


pip3 install --user .


as a standalone app

./kobuddy --help
usage: [-h] [--db DB] [--errors {throw,return}]
                   {books,progress,annotations} ...

Library to parse and provide Python interface for your Kobo reader

positional arguments:
    books               print all books
    progress            print all book reading progress
    annotations         print all annotations (bookmarks/highlights/comments)

optional arguments:
  -h, --help            show this help message and exit
  --db DB               By default will try to read the database from your
                        Kobo device. If you pass a directory, will try to use
                        all Kobo databases it can find.
  --errors {throw,return}
                        throw: raise on errors immediately; return: handle
                        defensively long as possible and reasonable

Example of printing reading progress:

Perihelion Summer by Greg Egan
Started : 27 Jul 2019 14:39
Finished: 05 Oct 2019 14:00
-- 27 Jul 2019 14:39: reading
-- 04 Aug 2019 16:40: highlight
-- 27 Aug 2019 12:33: reading: 25%
-- 02 Oct 2019 17:33: reading: 39%, read for 7 mins
-- 02 Oct 2019 17:42: reading: 46%, read for 8 mins
-- 02 Oct 2019 17:46: reading: 48%, read for 3 mins
-- 02 Oct 2019 17:48: reading: 50%
-- 02 Oct 2019 17:52: reading: 52%, read for 4 mins
-- 02 Oct 2019 21:49: reading: 75%
-- 02 Oct 2019 21:50: reading: 76%, read for 29 mins
-- 05 Oct 2019 11:56: reading: 86%, read for 14 mins
-- 05 Oct 2019 13:50: reading: 90%
-- 05 Oct 2019 14:00: reading: 100%, read for 19 mins
-- 05 Oct 2019 14:00: finished, total time spent 200 mins

as a library

import kobuddy
return kobuddy.get_books()[8: 10]
[Blindsight by Peter Watts, Classical Mechanics by John C. Baez & Derek K. Wise]

You can also find some examples in Orger or my package.

If you are looking for some specific Kobo events, check out EventTbl class, there is a good chance it’s been reverse engineered.

as a backup tool

./backup --help
usage: [-h] [--label LABEL] path

Backup tool for Kobo device database. You can run it via cron, e.g. every
minute and next time you connect you book via USB database would be backed up.
Potentially you could also add the script to udev rules.

positional arguments:
  path           target directory or file to dump the database

optional arguments:
  -h, --help     show this help message and exit
  --label LABEL  device label (check lsblk if default doesn't work)

Related projects/services

You can’t perform that action at this time.