No description
  • Python 97.5%
  • Shell 2.5%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-10-12 18:05:09 +00:00
.idea Initial commit 2026-08-21 13:39:15 +02:00
flatpak Add Flatpak packaging 2026-10-12 17:30:15 +00:00
mbox_viewer Improve UI and store attachment paths relative to the data dir 2026-10-05 20:57:13 +02:00
snap Release 0.1.5 2026-10-05 21:04:30 +02:00
.gitignore Add Flatpak packaging 2026-10-12 17:30:15 +00:00
mbox-viewer Split app from one huge file into seperate files and functions 2026-08-22 09:37:14 +02:00
mbox-viewer.desktop Initial commit 2026-08-21 13:39:15 +02:00
mbox-viewer.png Initial commit 2026-08-21 13:39:15 +02:00
README.md Update README.md 2026-10-12 18:05:09 +00:00
requirements.txt Split app from one huge file into seperate files and functions 2026-08-22 09:37:14 +02:00

mbox-viewer

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

Resetting

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