Mbox Viewer

A GTK4 desktop app for reading and searching .mbox archives on Linux.

An .mbox file is just every message in a mailbox concatenated into one long text file. That makes it awkward to work with: there is no index, no random access, and searching means scanning the whole file every time. Mbox Viewer imports the archive once into a local SQLite database — one row per message, plus a full-text search index — so afterwards every message is individually addressable and searching across subjects, addresses and message bodies is effectively instant, even for large archives.

What it does

• Import a single .mbox file, or a folder (every mbox file underneath it is imported). Re-importing is cheap: a file whose modification time hasn't changed is skipped; a changed file is re-parsed and its old messages replaced.
• Full-text search (SQLite FTS5) over subject, From, To, Cc, the plain-text body and the HTML body. Multiple words are AND-ed together. Search runs only when you press Enter or click Search, never while you type. If your SQLite build lacks FTS5 the app falls back to slower LIKE matching automatically.
• Browse messages in a list that loads in chunks of 50 as you scroll, sortable newest- or oldest-first. A sidebar lists each imported source file with its message count.
• Read messages with headers, the HTML body rendered in WebKitGTK (falls back to plain text if WebKit isn't installed), an inline-image gallery, and an attachments list with Open and Save buttons.
• Clear everything (database + extracted files) from the toolbar when you're done.

Imported data lives in ~/.mbox-viewer/:

• messages.db — the SQLite database (stores the full original message as a BLOB, so expect it to be roughly the size of the source archives plus index overhead).
• attachments/ — attachments and inline images extracted to disk, one folder per message.

Requirements

• Linux with a working GTK 4 stack. This is a GTK/GObject app; it does not run on Windows or macOS.

• Python 3.10+ (uses the standard-library mailbox, email and sqlite3 modules; developed against Python 3.14).

• PyGObject and pycairo — installed from requirements.txt (below).

• System GObject-introspection typelibs, from your OS package manager, not pip:

  • GTK 4 — required.
  • WebKitGTK 6.0 — optional; without it, HTML emails are shown as plain text.

  On Arch: sudo pacman -S gtk4 webkitgtk-6.0 On Debian/Ubuntu the equivalents are roughly gir1.2-gtk-4.0 and gir1.2-webkitgtk-6.0, plus the GObject-introspection dev package PyGObject needs to build (libgirepository1.0-dev or libgirepository-2.0-dev, depending on release).

• SQLite built with FTS5 for fast search. Most distributions ship this by default; the app still works without it, just more slowly.

Install

git clone ssh://git@forgejo.vosjes.cloud/yarrith/Mailbox_Viewer.git
cd Mailbox_Viewer

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

PyGObject binds to the GTK/WebKit libraries already installed on the system, so make sure the system packages listed above are present before or after creating the virtualenv.

Run

From the repository root:

./mbox-viewer                       # launches the GUI (activates ./venv first)
./mbox-viewer path/to/archive.mbox  # open the GUI and import this file
./mbox-viewer path/to/maildir/      # open the GUI and import every mbox under here

Or without the wrapper script, with the virtualenv active:

python3 -m mbox_viewer [FILE_OR_FOLDER ...]

You can also import from inside the app with the toolbar's open button, so passing a path is only a convenience.

Desktop integration (optional)

mbox-viewer.desktop registers the app as a handler for application/mbox so you can open .mbox files from a file manager. To use it, put the mbox-viewer script on your PATH, then install the launcher and icon:

install -Dm644 mbox-viewer.desktop ~/.local/share/applications/mbox-viewer.desktop
install -Dm644 mbox-viewer.png     ~/.local/share/icons/mbox-viewer.png
update-desktop-database ~/.local/share/applications

Snap package

A snap/snapcraft.yaml is included. Build and install (or download from releases) it with:

snapcraft pack
sudo snap install --dangerous ./mbox-viewer_*.snap

The snap targets core24 and uses the gnome extension, so GTK 4, PyGObject, the SQLite build (with FTS5) and the desktop integration libraries come from the shared GNOME platform snap instead of being bundled. That platform only ships the GTK3-based WebKit2 4.1, so the snap bundles the GTK4 WebKitGTK 6.0 stack from the Ubuntu archive to render HTML message bodies (a layout binds WebKit's helper process path to the staged copy). Without it the app falls back to plain text. The snap also plugs network so WebKit can fetch remote images referenced by HTML mail; inside the sandbox the app bypasses WebKit's xdg-desktop-portal proxy resolver, which otherwise fails and blocks all network loads.

Resetting

Use the trash button in the toolbar, or just delete ~/.mbox-viewer/. The next launch recreates it empty.