Readwyn 0.1.0

What is in the hidden .kobo folder on a Kobo, and what is KoboReader.sqlite?

The .kobo folder is where a Kobo keeps its own working files: its database, the encrypted copies of books you bought from Kobo, the dictionaries, a settings file, and a small file that names the model and the software version. KoboReader.sqlite is the database. It's an ordinary SQLite file, and it holds the list of books on the device and almost everything you do with them: highlights, notes, bookmarks, how far you've read, ratings, time spent reading, collections, and the words you saved to My Words. If you can't see the folder at all, that's by design on a Mac: its name starts with a full stop, and macOS hides such folders unless you ask to see them.

Showing the folder

Connect the Kobo with its cable and tap Connect on the “Computer detected” window. The Mac then gets a drive named KOBOeReader, as Kobo's guide to adding files says. If the drive itself doesn't appear, that's a different problem, covered in why your Kobo does not show up on a Mac.

Open the drive in Finder and press Command-Shift-full stop. Macworld describes the hidden items coming back “in a grayed-out state”, and the same keys hide them again. TidBITS gives the reason they were hidden: some Unix files and folders start with a period, so they're hidden by default. On Windows 11, Microsoft's help page says to choose View, Show, Hidden items in File Explorer. On Windows 10 it's View, Options, “Change folder and search options”, then “Show hidden files, folders, and drives” on the View tab.

What the folder holds

The contents differ by model and software version, but these are the parts you're most likely to meet:

  • KoboReader.sqlite, the database. More on it below.
  • version, a text file of about 100 bytes. It holds the serial number, the software version, and, at the end, a product ID that identifies the model.
  • kepub, the books from the Kobo store. The MobileRead wiki describes files with long numbered names and no extension, one per book, most of their contents encrypted.
  • dict, the dictionaries. On a Kobo Libra Colour we examined, it held dicthtml.zip for English and a dicthtml-<language>-en.zip file for German, Spanish, French, Italian, Dutch and Portuguese. A custom-dict folder next to it takes your own dictionaries, which how e-reader dictionaries work explains.
  • Kobo/Kobo eReader.conf, the settings file. The MobileRead wiki's page of configuration options lists settings that you can add to this file by hand, for example ExcludeSyncFolders, which “controls which folders are not processed into the database”. Many entries there are marked as unknown or broken on recent software.

One thing the folder isn't is a place for your own books. Kobo's article on the 6.0 update says that books sideloaded into the hidden .kobo folder weren't kept through the update to 6.0, and that books put there after it aren't imported into My Books. The article is about the Libra Colour, Clara BW and Clara Colour. Kobo's advice is to put them at the top level of the drive instead.

Inside KoboReader.sqlite

What follows comes from Readwyn's study of a Kobo Libra Colour on software 4.45, whose database reported DbVersion 176. Other versions can lack a table or a column.

TableWhat it holds
contentA row for each book, with ContentType 6, and rows for its chapters. A book row carries ReadStatus (0 unread, 1 reading, 2 finished), ___PercentRead, DateLastRead, and TimeSpentReading in seconds.
BookmarkHighlights, notes, dog-ears and stylus drawings, one row each. A highlight's Color is 0 to 3: yellow, pink, blue, green.
ratingsYour star rating of each book, 1 to 5.
Shelf and ShelfContentYour collections, and which books are in each.
WordListMy Words: the word, the book, the dictionary, and the date you saved it.

A few details explain what you see when you open it. Books are named by where the Kobo sees them, so a sideloaded KEPUB's ID looks like file:///mnt/onboard/<path>.kepub.epub. Yes or no values are often the text true or false, not a number. A collection's books are marked rather than removed: a ShelfContent row has an _IsDeleted flag, and a row with it set to true counts as gone. A Bookmark row has a Hidden column too, normally the text false; Readwyn treats a row with it set as deleted. Dates come in more than one form, sometimes 2026-10-03T20:19:47.911 and sometimes 2026-10-03T20:19:47Z. And WordList has no sentence and no position: only the word you saved, its book, the dictionary you looked it up in, and the time.

Opening it without harming it

The database uses SQLite's write-ahead log, so changes can sit in a KoboReader.sqlite-wal file beside it before they reach the main file. The SQLite documentation warns that the WAL file is part of the database: copy the database without it and committed changes can be lost, or the file can be corrupted.

So the safe way to look is to copy KoboReader.sqlite, and a -wal file if there is one, to your Mac, eject the Kobo, and open the copy. DB Browser for SQLite, an open-source viewer for macOS, Windows and Linux, shows each table like a spreadsheet. Editing the original on the Kobo is riskier, and it's where the WAL bites: the Kobo wants no -wal or -shm file when you eject, yet you must never delete a -wal file by hand. SQLite says the only safe way to remove one is to open the database and close it again, and the sqlite3 that comes with macOS leaves it in place even then. Explore the copy, and leave the original alone.

Readwyn reads this database over USB to bring a Kobo's highlights, notes, progress and saved words into your library. When a sync writes back, it first copies KoboReader.sqlite into its app folder on your Mac, and how Readwyn writes to a Kobo safely gives the rest of the steps.