Getting help.

The library starts empty.

That is deliberate: the shelf holds what you put on it, and nothing arrives uninvited. A brand-new install shows an empty library with a single instruction — tap + to import a book, add a collection, or load the bundled classics.

So if Walnut Reader looks bare after you install it, nothing is broken. Pick one of the two ways in below.

The sixteen classics, in one tap.

Tap + → Find Books → Add Samples. Sixteen public-domain editions — Moby-Dick, Dracula, Frankenstein, Pride and Prejudice, The Odyssey and the rest — are typed and filed into a Classics shelf in about a second. They need no download and no account, and they are yours to keep.

Running it again is safe: books already in your library are skipped, so a second tap cannot produce duplicates.

The same sheet holds links to Standard Ebooks and Project Gutenberg, which open in Safari for anything the bundled sixteen do not cover.

Adding your own books.

Walnut Reader reads EPUB and PDF. Three ways in, all of them local:

• From the app. Tap + → Add Books and pick files from Files, iCloud Drive, or any provider you have turned on.
• From any other app. Open a book's share sheet and choose Open in Walnut Reader — the file is copied in and the book appears on the shelf.
• From the Files app. Walnut Reader's folder is visible under On My iPhone → Walnut Reader. Drop files in and they show up in the library.

Title and author are read out of the file itself. To correct them, long-press the book and edit the details — the file on disk is renamed to match, so the name you see is the name on the file.

If a book won't open.

It imported, but won't open

The usual cause is DRM. Books bought from Kindle, Apple Books, Google Play or borrowed from a library are encrypted, and Walnut Reader reads ordinary, unprotected EPUBs and PDFs — it has no store account and no licence server, so a protected file cannot be unlocked. DRM-free EPUBs (Standard Ebooks, Project Gutenberg, most publisher-direct and indie files, and anything you export yourself) open fine.

It won't import at all

If the import fails, the file is usually incomplete — an interrupted download, or a partial AirDrop. Download it again and retry. A very large PDF can also take a moment on the first open while the app lays out its pages; it is working, not stuck.

Search finds nothing in a PDF

Scanned PDFs are pictures of pages. They open and read perfectly well, but there is no text layer for search to look at — that is a property of the file, not the app.

The cover is wrong, or there is none

Some EPUBs ship no cover image, and some label it in a way the app cannot use; those books show a plain plate on the shelf instead. Editing the book's details does not change its cover — the cover comes from inside the book file.

Setting the page your way.

Hide the chrome

Tap the middle of the page and the bars, counter and clock all go — the reading area does not shift when they do.

Two ways to move through a book

Page Turns lays the book into pages, with a counter such as “9 / 228”; a tap in the left third of the page goes back and the right third moves on. Vertical Scroll runs the book as one continuous column. Long-press the settings button to switch between them without opening anything.

Type, theme and layout

Reader settings open as one sheet with a live preview above each card, so you can see the change before you leave:

• Theme — Light, Sepia, Dark, or Automatic, which follows your device and switches while you read. Dark is true black, for OLED screens; PDFs stay white for document fidelity.
• Brightness — moves your device's actual screen brightness, not a dimming layer over it.
• Typeface — the built-in faces, plus any font you add yourself: a .ttf, .otf or .ttc you import joins the menu.
• Size, margins, alignment — text size, four margin widths from Tight to Relaxed, and left, centred or justified paragraphs.
• Rotation — read in landscape, or lock the app to portrait while you read.

Every setting is remembered for the app, and changing any of them keeps your place — a font change will not send you back to the start of the chapter.

Finding your place again.

Close the app, come back later

You land exactly where you left off — in either reading mode, and after switching between them mid-book.

Bookmarks

The ribbon in the top bar is solid when the page you are on holds a bookmark and hollow when it does not. Tap once to mark the page, tap again to clear it. Long-press the ribbon for the whole list, newest first, each entry labelled with the nearest chapter and ready to take you back.

Search inside the book

Searching walks the entire book — every chapter, not just the one on screen — and shows a snatch of text with your word picked out and the page it lands on. Tap a result and the reader jumps there and flashes the match. All of it happens on your device; nothing is uploaded and nothing is indexed ahead of time.

The book's own contents

The contents sheet lists the book's own entries, as the publisher wrote them, each showing the page it starts on in your current layout. Books that ship no table of contents fall back to their chapter order.

Progress and statistics.

Continue Reading

A book joins Continue Reading the moment you open it — you do not have to turn a page first — and stays until you reach the end. Finish it and it moves to Finished; re-open it and it comes straight back. Progress bars appear once a book has been opened; a book you have never opened shows a bare shelf card instead of a bar at zero.

Reading Stats

Gear → Reading Stats shows today's time, total reading time, words read, your current and longest streak, a seven-day chart, a per-book breakdown and your recent sessions. Two rules keep it honest: time is counted only while the reader is on screen (leaving the app pauses the clock), and pages count as you move forward, so re-reading a passage does not double-count. A streak survives a day you have not read yet.

Per-book totals survive deleting the book, so your history stays complete. To clear the record without touching your library, use Reset All Statistics — books, shelves and bookmarks stay exactly where they are.

Collections.

Collections are shelves you name yourself — school, work, a mood, a year. Add one from + → Add Collection…, then long-press a book to file it onto a shelf.

Each shelf keeps its own sort order, including a Manual mode with drag-to-reorder, so tidying a shelf never disturbs the main library. Rename a shelf or delete it from the shelf's own menu; deleting a shelf leaves its books in the library.

A new iPhone.

There is no Walnut account and no cloud sync, so moving to a new phone is done with a file you hold:

• On the old device — Settings → Export App State…. The app builds one JSON file with your progress, bookmarks, Continue Reading and Finished state, collections, reading history and reader settings, then hands it to the iOS share sheet. Send it to yourself, or AirDrop it across.
• On the new device — add your book files first (via Files, iCloud Drive, or the Files-app folder), then Settings → Import App State… and pick the file. Progress and shelves reattach to the books already in the library; the app tells you if a book is missing so you can add it and import again.

The export deliberately does not include the book files themselves — your books are ordinary files, and they travel however you prefer to move files.

If you have iCloud Backup turned on, restoring your whole device also brings the app's data back; that is an Apple feature rather than an in-app one.

Starting over.

Three levels, smallest first — pick the one that matches what you want gone:

• Reset Settings returns every reading preference to its default. Books, progress, bookmarks and history are untouched.
• Reset All Statistics clears the reading record only.
• Reset All Data is the fresh install: the library, the book files, imported fonts, reading history, caches and settings all go. It sits on its own confirmation screen so it cannot be triggered by a stray tap.
• Delete the app does the same and more thoroughly — everything it holds goes with it.

Still stuck?

Write to walnut@benfrancis.me — a person reads that inbox, and it is the same person who builds the app.

Three details make a fix much faster: what you did, what happened instead, and your device and iOS version (Settings → General → About). A screenshot helps when the problem is visual. Do not send book files unless asked — a title and where it came from is almost always enough to identify a cause.

One thing we cannot do: look anything up on your behalf. Walnut Reader sends us nothing, so there is no account or log for us to search — which is the point, and occasionally the inconvenience.