mutool is the MuPDF scalpel you reach for when a PDF looks innocent but probably isn't

If you handle PDFs for a living, you learn two things early: never trust a document you did not generate, and your GUI viewer is not telling you everything. mutool is the command-line utility that ships with MuPDF, used for inspecting, rendering, converting and repairing documents using the same engine that drives the viewer. It keeps work local, fast and scriptable, which is exactly what you want when the file might be booby-trapped with "helpful" features.

MuPDF itself focuses on viewing and converting PDF, XPS and some e-book formats, per the project documentation, so mutool inherits that reach for batch jobs and automation [https://mupdf.readthedocs.io/en/latest/]. The license is AGPL-3.0 or later, which matters if you expose it as a service rather than run it on your own machine [https://github.com/ArtifexSoftware/mupdf]. More on that below.

What it actually does day to day

• Quick inspection. List the basics of a file: page count, page sizes, metadata, encryption status, and object graph features. Think of it as a stethoscope for "why is this PDF 200 MB and has two pages."
• Rendering. Turn a page into a bitmap or vector output for thumbnails, previews, or print pipelines. When in doubt about weird transparency or overprint, render it. Pixels do not lie; content streams often do.
• Rewriting and fixing. Rebuild cross-reference tables, remove unreachable objects, and normalize structure. This can rescue files with a corrupt xref or bloated incremental histories.
• Extraction. Pull out embedded images, fonts or attachments for separate handling and inspection.
• Page surgery. Split giant poster pages into tiles or otherwise reshape geometry for devices that choke on 2-meter MediaBoxes.

It works by parsing the object graph with MuPDF's libraries, then either interpreting page content to render it, or walking and rewriting objects when you need a cleaner, smaller, or saner file. The difference matters. Rendering answers "what does it look like"; rewriting answers "what is in the file." If you skip that distinction, you wake up with a "fixed" document that looks perfect and fails an audit, or the reverse.

Why people use mutool in privacy-first workflows

Nothing leaves your machine unless you push it. That is the whole point. For browser-centric teams, the usual pattern is to keep file handling local: the browser UI for choosing files, a local helper that invokes mutool for rendering or extraction, and a strict no-upload rule for sensitive docs. If your pipeline is "drag a PDF into a website," you have already decided where your secrets go. If it is "drag a PDF into a local tool that calls mutool," you have not.

A note on licensing if you automate

MuPDF is AGPL-3.0 or later [https://github.com/ArtifexSoftware/mupdf]. If you wrap mutool behind a network service and let others use it over a network, the AGPL's network clause is in play. If you ship an on-device tool for in-house use, you are within the license. If you need different terms, Artifex sells commercial licenses; the README points you to sales@artifex.com.

Practical notes from the trenches

• Render to simplify. If you need to flatten form fields, transparency, overprint or "creative" blending, a render step is the most deterministic way to purge viewer-dependent behavior. Yes, it costs pixels. It also costs fewer nights.
• Rewriting is not archiving. Rebuilding a file often discards incremental edit history. That is good for file size, bad for forensic traceability. Keep the original if you might need to prove anything later.
• Object IDs are not stable. If you plan to extract "object 42" after a clean-up pass, expect object numbers to change. Identify content by page and role, not by pre-clean object number.

Where this goes sideways

• Symptom: "The PDF's digital signature was fine yesterday; now it is invalid." Cause: you rewrote the file to "clean" or linearize it. Any byte-for-byte change breaks the original signed ranges. Fix: never rewrite signed PDFs if you need the signature to validate. Work on a copy, and if you must "fix by rendering," render to a new PDF or image and treat it as a derivative without the original signature.

• Symptom: "Extraction missed some content I can see on the page." Cause: not everything you can see lives in the page content stream. Annotations, optional content groups (layers), and embedded files are different beasts. Fix: use the extraction mode that targets the asset you need, or render the page to bake everything visible into pixels when you only need appearance.

• Symptom: "Output images are enormous and downstream systems time out." Cause: rendering vector-heavy pages at print DPI produces multi-megabyte bitmaps. Fix: pick a resolution appropriate to the task. Thumbnails and previews want far less than prepress. Keep one render setting per use case and do not reuse your 600-dpi print preset for a web gallery.

• Symptom: "After cleaning, compliance checks complain about missing structure or tags." Cause: a normalization pass can drop or rewrite features that a checker expects to be present in a specific form, especially if the original had incremental edits glued on. Fix: run checks on the original first to understand what you are preserving, and test your clean-and-rewrite profile against the exact validator you must satisfy.

• Symptom: "Attachments I expected are gone in the output." Cause: a rewrite focused on page content will not preserve unrelated embedded files unless told to. Fix: treat attachments as first-class citizens in your workflow. Extract them before rewriting, and reattach only what you intend to ship.

• Symptom: "Tiled output page sizes are odd, and margins look wrong." Cause: PDFs have multiple page boxes. If you split a page without being explicit about which box you take as truth, you inherit someone else's CropBox argument from 2012. Fix: settle on the box you mean to honor, preview a few pages, and only then batch.

Design oddities that make sense once you know them

PDFs are append-only by design. That "incremental update" lets editors add a revision without rewriting the whole file. It also means a PDF will happily keep five generations of edits stapled to the back like a cursed genealogy. Tools like mutool that rewrite from scratch are doing you a favor by reassembling one coherent body from the bones. Just do not call it the original any more.

Another quiet truth: "looks identical" is often the correct success criterion. The standard permits all sorts of functional features that are not reliably portable across viewers. If your job is to make the invoice render identically everywhere, a well-chosen mutool render-and-regenerate step is not a hack. It is the adult decision.

If you need help or to report a problem

The MuPDF team points people to their docs [https://mupdf.readthedocs.io/en/latest/], and to their Discord for developer chat [https://artifex.com/discord/artifex]. Bugs go to Ghostscript's Bugzilla with MuPDF as the component [https://bugs.ghostscript.com/]. If the issue involves a specific file, attach the file. They say so in the README.

References

• MuPDF documentation home: https://mupdf.readthedocs.io/en/latest/
• MuPDF install guide: https://mupdf.readthedocs.io/en/latest/guide/install.html
• MuPDF GitHub mirror and license: https://github.com/ArtifexSoftware/mupdf
• Bug reporting (Bugzilla): https://bugs.ghostscript.com/
• Developer chat (Discord): https://artifex.com/discord/artifex

---