- Python 97.5%
- Shell 2.5%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| .idea | ||
| flatpak | ||
| mbox_viewer | ||
| snap | ||
| .gitignore | ||
| mbox-viewer | ||
| mbox-viewer.desktop | ||
| mbox-viewer.png | ||
| README.md | ||
| requirements.txt | ||
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
.mboxfile, 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 slowerLIKEmatching 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,emailandsqlite3modules; 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.0On Debian/Ubuntu the equivalents are roughlygir1.2-gtk-4.0andgir1.2-webkitgtk-6.0, plus the GObject-introspection dev package PyGObject needs to build (libgirepository1.0-devorlibgirepository-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.