How to use

Choose a feature below to find its usage guide. These guides cover the MuPDF backend for Okular. In Okular’s backend configuration, select MuPDF-NG; settings paths below refer to its General, PDF, and ePUB tabs.

Safety & Isolation

Documents are parsed and rendered in a separate worker process. In General → Security → Sandbox Enforcement, choose:

• Strict (default): open documents only when the worker reports a fully hardened sandbox.
• Relaxed: allow documents to open even when some sandbox protections are unavailable. Available protections still remain active.

Apply the setting and reopen a document if it was blocked by Strict enforcement. Enable Show notification when sandbox is degraded to display warnings about incomplete protection.

Blocked documents and warnings

When Strict enforcement blocks a document because the worker is not fully hardened, a guidance card appears instead of the document.

When degraded-sandbox notifications are enabled, Okular also reports incomplete protection in a warning banner. This example shows an unconfined worker; Relaxed enforcement allows documents to open in this state.

Probe the worker

Run the installed worker as your normal user to check the protections available on your system. For a typical /usr/lib installation:

/usr/lib/okular-mupdf-ng/mupdfng-worker --sandbox-check
/usr/lib/okular-mupdf-ng/mupdfng-worker --sandbox-check=json

Example output from an x86_64 Debian-style installation:

/usr/lib/x86_64-linux-gnu/okular-mupdf-ng/mupdfng-worker --sandbox-check
Sandbox check on host:
  landlock: yes abi=9
  seccomp: yes
  linuxNamespace: yes
  resourceLimits: yes
  memoryProtection: yes
  fullyHardened: yes
  partiallyActive: no

The worker location depends on the package’s library directory; it may use lib64 or a multiarch directory. For a source build, use ./build/bin/mupdfng-worker --sandbox-check.

The probe activates the sandbox in a short-lived process and reports Landlock, seccomp, namespaces, resource limits, memory protection, and any reason for degraded protection. Exit code 0 means fully hardened, 1 means partially active, and 2 means unconfined.

Strict/Relaxed is the plugin’s enforcement policy; the probe reports whether runtime protections can satisfy Strict on this host. It does not change the policy or inspect an already running Okular worker.

OCR

Install a language model

Install a Tesseract language model for the document’s language. The examples below install English (eng); use the search command for your distribution to find other language models.

Ubuntu / Debian

sudo apt update
sudo apt install tesseract-ocr-eng

Find other models: apt search tesseract-ocr-. Package references: Ubuntu, Debian.

Fedora

sudo dnf install tesseract-langpack-eng

Find other models: dnf search tesseract-langpack. Package reference.

openSUSE

sudo zypper install tesseract-ocr-traineddata-eng

Find other models: zypper search tesseract-ocr-traineddata. Package reference.

Arch Linux / Manjaro

sudo pacman -S tesseract-data-eng

Find other models: pacman -Ss tesseract-data. Arch package reference.

After installing a model, restart Okular and reopen the backend settings so it can discover the new language data. Model names use Tesseract language codes, which may differ from your desktop’s language code.

Configure OCR

In PDF → Optical Character Recognition, select the Tesseract Model and Tesseract Quality. Adjust the character-count threshold to control when automatic OCR runs.

For one PDF, open Tools → Document Settings and uncheck Use Global in the Tesseract OCR section. Choose its language, quality, trigger mode, and notifications, then apply. These settings are remembered for that PDF and apply without reopening it. Check Use Global to remove the override. The OCR menu controls global defaults unless an override exists. With an override, it shows (Local) and edits that PDF’s settings; choose Use Global there to restore inheritance.

Enable OCR

Choose Tools → Tesseract OCR → Automatic for scanned pages, or On to run OCR even when a page already contains text. Choose Off to stop automatic recognition.

View the pages to recognize them, then select or search the recognized text. Recognition results are cached; OCR does not add a text layer to the saved PDF. You can also assign a keyboard shortcut to toggle OCR.

Kindle formats

Open DRM-free AZW3 (KF8) and single-container KFX books directly in Okular. They are converted to ePUB in memory before rendering, so the ePUB layout settings also apply to them.

Encrypted books and KFX books split across multiple files are not supported. Legacy MOBI is handled separately; it supports uncompressed and PalmDOC-compressed books.

Kindle books can export to ePUB, PDF, or plain text. Conversion may change book-specific formatting.

Ebook customisation

ePUB, legacy MOBI, AZW3, and KFX use the same rendering and layout engine. The font, page size, and custom CSS settings below apply to all four formats.

1. Open Tools → Document Settings for a local book and uncheck Use Global under Ebook layout.
2. Set Font Size, Font Family, and Page Size.
3. Expand Custom CSS to add your own document styles.
4. Apply the settings. The book reloads with the new layout.

Applied overrides are remembered for this document. Select Use Global to remove the layout override. Set defaults for other books under ePUB → Page Layout in the backend settings.

For example, this rule increases inherited line spacing:

body { line-height: 1.8; }

A document’s own rules on individual elements can override inherited styles. Changing the layout can change page counts and text positions.

Document Theming

Tools → Document Theme controls the global theme by default. Use Tools → Document Settings to save a theme for one document. Its menu then shows (Local) and edits that override. Choose Use Global to remove the override and return to the global theme. Themes apply immediately, independently of ebook layout.

Dark always recolors vectors and checks each raster image separately: mostly dark images stay uninverted at 80% brightness, while lighter images are inverted. Light vector text over a preserved dark image may lose contrast. Dusk preserves vector colors only when both the page and its border are mostly dark, but still dims images. Dusk distinguishes images from vectors, not their content: scanned text dims with its image, and vector illustrations follow the text palette.

For pages that use non-normal blend modes or knockout groups, Dark transforms the completed page to preserve correct compositing. Selective image inversion and 80% image dimming are unavailable on those pages. PDF highlights’ Multiply blending does not trigger this fallback, keeping highlighted text readable unless other blends require it.

Themes affect viewing only. OCR, printing, exports, and the document’s saved content retain their original colors. You can assign keyboard shortcuts to toggle themes.

Loading placeholders match Twilight, Dusk, and Dark when Okular’s per-page placeholder color API is available. On older versions, Dusk and Dark temporarily use accessibility Change Paper Color. These settings are not saved, and user preferences are restored when no document needs the workaround. Twilight placeholders may remain white on older versions.

See the feature maturity matrix for testing coverage and limitations.

Keyboard shortcuts

1. Open a document with the MuPDF backend, then choose Settings → Configure Shortcuts….
2. Expand okular_mupdfng or search for the action name.
3. Select an action, assign a shortcut, and apply the change.

These actions have no default shortcuts. Toggle Tesseract OCR switches between On and the previous OCR mode. Toggle Twilight Mode, Toggle Dusk Mode, and Toggle Dark Mode switch between the selected theme and Default.

Link Preview

Introduced in v0.5.2, link preview shows an internal link’s destination when you hover over it, without leaving the current page. Use it to check references and other linked locations within the document.

In the MuPDF-NG backend configuration, open General → Behavior → Display link preview on hover and choose:

• Off (default): disable link previews.
• Adaptive Size: adapt the preview to the Okular window and current page rendering scale.
• Small or Large: choose a preview size.

Move the pointer into the preview to keep it open. Scroll or drag within it to read around the destination, including neighboring pages. Press Esc or move the pointer away to dismiss it. Clicking the original link still navigates to its destination.

PDF Heuristic Outline

1. In General → Behavior, enable Generate a table of contents when none is embedded.
2. Open a PDF without an embedded outline and show Okular’s Contents sidebar.
3. Select a generated entry to jump to its page.

The generated TOC uses document headings and layout cues. It is a navigation aid and may miss or misclassify headings. An embedded outline takes precedence, and generated results are cached without modifying the PDF.

Annotations & Forms

Annotations

1. Open a PDF, then use Okular’s annotation tools to select a text, highlight, line, shape, ink, stamp, or caret tool.
2. Add the annotation to the page and adjust its properties as needed.
3. Save the PDF, or use Save As to keep a separate copy.

Use undo and redo to revise edits. To share PDF annotations separately, use XFDF export; to bake them into page content, use flattened PDF export.

PDF Forms

1. Open the PDF and choose View → Show Forms, or use the Show Forms button when Okular offers it.
2. Edit text fields, checkboxes, radio buttons, or choice fields.
3. Save the PDF or use Save As to keep a copy with your edits.

For date and time fields, hover over the form field to check its tooltip for the expected input format, such as yyyy/mm/dd for a date, when format guidance is available.

AcroForm controls are supported; XFA forms are detected but not implemented. Some calculations and buttons need the optional PDF JavaScript setting.

PDF Export

For PDF documents, use File → Export As to create a flattened PDF or an XFDF annotation file. All supported document formats can export plain text; ePUB, MOBI, AZW3, and KFX can export to PDF.

Flattened PDF

Choose File → Export As → Flattened PDF and save a new output file. Annotations and form fields are baked into page content, so they no longer remain editable controls in that copy. Keep the original PDF if you need to edit them later. The export leaves the open source document unchanged and ignores document themes.

XFDF annotation file

Choose File → Export As → Annotation File (XFDF), then save the output and share it with the corresponding PDF. The file picker may use an .xml extension; its contents are XFDF. This keeps annotations separate from the PDF. XFDF export does not support PDFs containing rotated pages.

Document themes affect viewing only, so printing and exports use the document’s original colors.

Ebook export

PDF

1. Open the ePUB, MOBI, AZW3, or KFX document and configure its page layout.
2. Choose File → Export As → PDF and an output filename.
3. Wait for the export-complete notification, then open the resulting PDF.

The export uses the current reflow layout. Document themes do not change its colors. The resulting PDF has fixed pages rather than reflowable text.

ePUB and AZW3 conversion

• For an AZW3 or KFX book, choose File → Export As → ePUB.
• For an ePUB book, choose File → Export As → Kindle (AZW3).

Choose an output filename. These exports produce reflowable books; the current page layout and document theme are not baked into the output. Legacy MOBI supports PDF and plain-text export only.

Signatures

Open a signed PDF and use Okular’s Signatures panel to inspect the signature and certificate details. Certificate trust and signature validity are separate checks.

To sign a PDF, configure an NSS certificate database in PDF → Crypto Engine, then use Okular’s signing action. Select a certificate with its private key, place the signature, and save the signed output.

Adjust the signature appearance in the PDF settings.

If no signing certificate is available, use the certificate manager to import one or create a self-signed certificate.

Cert Manager

In PDF → Crypto Engine, choose the default certificate database or a custom NSS database directory, and apply the setting.

1. Open Tools → Manage Certificates…, or the Manage Certificates button in the PDF settings.
2. Use My Certificates for signing identities and People for certificates trusted for verification.
3. Use Add Certificate to import a file, paste a PEM certificate, or create a self-signed certificate where available.

A signing identity needs its private key; a public certificate alone cannot sign. Self-signed certificates need separately configured trust before other readers will treat them as trusted.

PDF JavaScript

In General → Security, enable Enable JavaScript support, apply the setting, and reopen the PDF. The same reopen step applies when disabling it.

This optional, experimental feature supports MuPDF’s form calculations and field/button actions; it does not implement every Acrobat JavaScript API. The setting is unavailable when JavaScript support was disabled at build time.

Caching

OCR results, generated PDF TOCs, and ePUB layout accelerators are cached automatically. Reopening a document can reuse compatible results; changing relevant OCR or layout settings uses the corresponding cache.

In General → Cache Management, click Click to calculate cache storage size to measure usage. Open the button’s menu and choose Vacuum PDF TOCs, Vacuum ePUB Accels, Vacuum OCR, or Vacuum All to clean cached data.

The retention note shows when old cache files are removed automatically. Cache cleanup does not delete source documents or saved edits.