A MuPDF-based secure1 and fast2 backend for Okular. Document rendering is moved to an isolated and hardened worker process. This reduces the impact of MuPDF vulnerabilities while keeping Okular's desktop integration seamless. Supports PDF, ePUB, legacy MOBI, DRM-free AZW3 and single-container KFX books, and XPS/OpenXPS.
Installation
See INSTALL.md for community repos, prebuilt packages, build requirements, and instructions for building from source.
Motivation
Okular is an amazing piece of software: it's packed with good features; it's also extendable with a flexible plugin system. However, there are caveats that hold it back. This plugin solves the following issues with the current Okular's backends, with the hope of making it more complete:
- PDF is a complex format, it should not be parsed and rendered in Okular's memory space unconfined. See Chromium's Rule of Two.
- PDF backend with Poppler is rich in features, but sluggish on big PDFs. This is a known weakness of Poppler.
- Rendering quality of the default ePUB & MOBI backends are terrible, plus rendering speed is also painstakingly slow even on a high-end CPU.
- Okular lacks support for DRM-free Kindle ebooks like AZW3 (KF8) and KFX.
Architecture
The document engine runs in an isolated worker process, where potentially unsafe documents are parsed and rendered. See ARCHITECTURE.md for component responsibilities, IPC, shared rendering buffers, sandboxing, caches, and the source-tree layout.
Feature Comparison
| Feature Category | Capabilities | okular-mupdf-ng | Okular official backends |
|---|---|---|---|
| Safety & Isolation | Sandboxed out-of-process worker (Landlock, Seccomp, namespaces, resource limits) | ✓ | ✗ (in-process execution) |
| Smart Document Theming | Default, Twilight, Dusk, and Dark viewing themes for all supported formats | ✓ | ✗ (Accessibility color modes) |
| OCR for PDF | Built-in Tesseract page OCR engine | ✓ | ✗ |
| ePUB/MOBI customisation | Custom CSS, Page size, Font size, Font family | ✓ | ✗ (Font size only) |
| Certificate Manager | NSS certificate manager; manage trust and generate RSA and ECDSA P-256 signing certificates | ✓ | ✗ (Cert listing only) |
| Link Preview | Preview internal link destinations on hover | ✓ | ✗ |
| XFDF annotations | Import and export PDF annotations | ✓ | ✗ |
| Flattened PDF export | Bake annotations and form fields into PDF page content | ✓ | ✗ |
| PDF Heuristic Outline | Outline generation for PDFs that don't have embedded outline | ✓ | ✗ |
| ePUB/MOBI export | Export ePUB/MOBI to PDF, preserving links and TOC | ✓ (via MuPDF rendering) | ✗ (document print) |
| Signature Profiles | PDF Signature profiles and customisations | ✓ | ✗ |
| Formats | PDF, ePUB, MOBI, AZW3, KFX, XPS | ✓ | ✗ (PDF and basic ePUB/MOBI/XPS support) |
| PDF Forms | AcroForm text inputs, checkboxes, radio buttons, choices, and push buttons | ✓ (AcroForm; XFA detected only) | ✓ (AcroForm; XFA detected only) |
| PDF form JavaScript | Calculations and button/field-event actions | ✓ (MuPDF/MuJS executes in the sandboxed worker; experimental, opt-in) | ✓ (Poppler passes scripts to Okular, which executes them in QJSEngine) |
| Annotations | Text, highlight, line, shape, ink, stamp, caret | ✓ | ✓ (plus sound, movie & file-attachment annotations) |
| Document Tools | Text search, outline/TOC, links, fonts, metadata, embedded files | ✓ | ✓ |
| Printing & Exporting | Print & Export | ✓ | ✓ |
| PDF layers | Toggle optional content in the Layers sidebar | ✓ | ✓ |
Limitations
- MuPDF's ePUB & MOBI support are incomplete. ePUB 3.0 and modern MOBI are not fully supported, so some documents may render incorrectly.
- The NSS cryptographic code has not been fully audited.
- Sandbox is Linux only and its availability depends on Linux kernel and system support. Default to Strict Enforcement.
- Worker restart can not recover unsaved forms.
- Twilight, Dusk, and Dark prefer Okular's per-page placeholder color API when available. Older Okular versions use shared placeholder pixmaps and incomplete loading images. Extreme zoom or uncovered tile regions can still show default white placeholder with this fallback.
- AWZ3 and KFX support relies on boko to convert the formats to ePUB in-memory.
See the feature maturity matrix for feature-specific maturity and automated test coverage.
Changelog
See CHANGELOG.md for release highlights, fixes, and other changes.
Contributing
See CONTRIBUTING.md for contribution and testing guidelines. See SECURITY.md for the security contact.
Credits
This project learned from amazing projects below
- Okular Poppler Backend - Okular integration
- SumatraPDF - MuPDF API usage
- Zathura - Seccomp rules
- Sioyek - MuPDF API usage
Honorable mentions
Earlier research explored isolating document engines from desktop interfaces:
- Virtics: A System for Privilege Separation of Legacy Desktop Applications (2010), by Matt Piotrowski and Anthony D. Joseph, demonstrated an Evince-based PDF viewer with document processing and rendering isolated in an unprivileged Linux/KVM virtual machine.
- Clean Application Compartmentalization with SOAAP (2015), by Khilan Gudka et al., demonstrated an Okular Poppler renderer running in a separate sandbox process, with calls proxied across the generator interface.
License
Original project source code is licensed under the
GNU General Public License v3.0 or later (GPL-3.0-or-later),
unless otherwise indicated.
Third-party components retain their respective licenses and copyright notices:
- MuPDF, including its signature emblem:
GNU Affero General Public License v3.0 or later
(
AGPL-3.0-or-later). The worker links against MuPDF; its license applies to the engine as well as the emblem. GPLv3 permits this combination, with the AGPL's network-interaction requirements applying to the combined work; see GPLv3 section 13. - Allura font: SIL Open Font License 1.1.
- zpp::bits: MIT License.
- cxxopts: MIT License.
- boko: GPLv3 License.
Other dependencies and bundled resources, including fonts embedded by MuPDF, retain their upstream licenses. This summary does not replace the full license texts or component-specific notices.
-
To our knowledge, this is the first backend for a native Linux desktop document reader to isolate document parsing and rendering in a sandboxed worker process. ↩
-
In our five-document PDF benchmark, it was at least twice as fast as Okular's official Poppler backend. ↩