Skip to content
ArtifexSoftwarePublic

About

C# bindings for MuPDF

Topics

Resources

Stars

114 stars

Watchers

10 watching

Forks

Repository files navigation

MuPDF.NET

Docs Github Stars Discord Forum

MuPDF.NET is a C# library for reading, writing, rendering, and editing PDF, XPS, EPUB, and other document formats. It is a port of PyMuPDF to .NET, built on the MuPDF engine, with idiomatic APIs for C#, F#, and Visual Basic.

dotnet add package MuPDF.NET

Runnable samples (one project per feature) are in MuPDF.NET.Examples.

Markdown / JSON for LLM and RAG is in this package: Document.ToMarkdown, ToJson, ToText, ToChunks, and Utils.LoadAiAsync. Optional layout: Layout analysis. Office and HWP files: MuPDF.NET.Office. Do not add MuPDF.NET.PDF4LLM — that package is deprecated.


Contents


Why MuPDF.NET

  • Fast — built on MuPDF, with no mandatory GPU dependency
  • Accurate — text extraction with font, colour, and position metadata
  • Versatile — read, write, annotate, redact, merge, split, convert, and render
  • Multi-language — C#, F#, and Visual Basic; the API mirrors PyMuPDF so Python experience transfers directly
  • Barcodes — read and generate QR, Code 128, Data Matrix, PDF417, and more
  • LLM-ready — Markdown / JSON / text extract in this package; optional RAG helpers on .NET 8

Requirements

Requirement Version
.NET 8.0 or later (also .NET Standard 2.0 and .NET Framework 4.6.1+)
Visual Studio 2019 or 2022 (Windows)
OS Windows, Linux, macOS

Linux CLI install steps: Getting Started.


Installation

dotnet add package MuPDF.NET

Or in Visual Studio: NuGet Package Manager → search MuPDF.NET.

Install-Package MuPDF.NET
using MuPDF.NET;

The package includes the native MuPDF binaries. No separate download is required.

Office / HWP (DOC/DOCX, XLS/XLSX, PPT/PPTX, HWP/HWPX) is a separate commercial package (product page):

dotnet add package MuPDF.NET.Office

Call MuPDFOffice.Unlock once, then open those files with Document and the same ToMarkdown / ToJson / ToText APIs.


Layout analysis (optional)

GetLayout, FindTables, and layout-aware ToMarkdown can use pymupdf 2.1 as an optional layout worker (import pymupdf.layout). Without it, MuPDF.NET uses classic text extraction.

Requires Python 3.11+ on PATH. From any project that references MuPDF.NET:

dotnet msbuild -t:MuPDFNetSetupLayoutPython

That creates a per-user virtual environment and pip-installs both of these from PyPI:

Package Role
pymupdf==2.1 The worker. Layout is pymupdf.layout inside this package.
pymupdf-layout==2.1 Empty stub so older pymupdf-layout pins still install. It is not a second layout engine.

MuPDF.NET finds that venv automatically.

Using the worker means PyMuPDF is part of your solution, not only MuPDF.NET. PyMuPDF has its own license (Artifex Community License and commercial terms). A MuPDF.NET license does not by itself cover shipping or running PyMuPDF. If you do not want that, skip this setup target and keep classic extraction (Utils.UseLayout(false)). For commercial use of the worker, contact Artifex.

OS Location
Windows %LOCALAPPDATA%\MuPDF.NET\.venv-layout
Linux / macOS ~/.local/share/mupdf.net/.venv-layout

Check the install:

dotnet msbuild -t:MuPDFNetVerifyLayoutPython

On Ubuntu 22.04, install Python 3.11 first (python3 is 3.10 there):

sudo apt install python3.11 python3.11-venv python3.11-full

To use another Python 3.11+ interpreter that already has pymupdf 2.1, set MUPDF_NET_PYTHON.

bool layoutReady = Utils.LayoutPythonAvailable;  // worker can be imported
bool layoutActive = Utils.LayoutAvailable;       // provider is registered
Utils.UseLayout(false);                          // classic extraction

Quick start

Extract text

using MuPDF.NET;

Document doc = new Document("document.pdf");
Page page = doc[0];
TextPage tpage = page.GetTextPage();
Console.WriteLine(tpage.ExtractText());
doc.Close();

Convert to Markdown

using MuPDF.NET;

using Document doc = new Document("document.pdf");
Utils.UseLayout(false);                         // omit this line to use layout when installed
string markdown = doc.ToMarkdown(showProgress: false);
File.WriteAllText("document.md", markdown);

Search and highlight

using MuPDF.NET;

Document doc = new Document("document.pdf");
Page page = doc[0];
List<Rect> matches = page.SearchFor("invoice");
if (matches.Count > 0)
    page.AddHighlightAnnot(matches);
doc.Save("highlighted.pdf");
doc.Close();

Render a page to PNG

using MuPDF.NET;

Document doc = new Document("document.pdf");
Page page = doc[0];
Pixmap pix = page.GetPixmap();               // 72 dpi by default
pix.Save("page_0.png");
doc.Close();

Key capabilities

Area What you can do
Text extraction Plain text, JSON, XML, HTML, or structured dict with position and font metadata
Rendering PNG, JPEG, TIFF, BMP, or in-memory bitmaps at any DPI
Annotation Highlights, underlines, stamps, links, comments, and shapes
Redaction Permanently remove text, images, and graphics from a region
Merging & splitting Join PDFs, insert, reorder, rotate, and delete pages
Encryption Encrypt, decrypt, passwords, and permissions
Forms Read and write PDF form fields
OCR Image-heavy pages via Tesseract
Images Extract, insert, replace, and recompress (RewriteImages)
Barcodes Scan and generate QR, Code 128, Data Matrix, PDF417
LLM / RAG ToMarkdown / ToJson / ToText / ToChunks; Utils.LoadAiAsync; layout when the worker is installed
Office / HWP MuPDF.NET.Office; unlock, then use Document as usual

Code examples

Copy-paste snippets. Full apps are in MuPDF.NET.Examples.

Add a text watermark

using MuPDF.NET;

Document doc = new Document("input.pdf");
for (int i = 0; i < doc.PageCount; i++)
{
    Page page = doc[i];
    Font font = new Font("helv");
    TextWriter tw = new TextWriter(page.Rect);
    tw.Append(new Point(50, 100), "CONFIDENTIAL", font);
    tw.WriteText(page);
}
doc.Save("watermarked.pdf");
doc.Close();

Redact a region

using MuPDF.NET;

Document doc = new Document("input.pdf");
Page page = doc[0];
Rect region = new Rect(0, 0, 200, 200);
page.AddRedactAnnot(region, fill: new float[] { 1, 0, 0 });
page.ApplyRedactions();
doc.Save("redacted.pdf");
doc.Close();

Merge two PDFs

using MuPDF.NET;

Document docA = new Document("first.pdf");
Document docB = new Document("second.pdf");
docA.InsertPdf(docB);
docA.Save("merged.pdf");
docA.Close();
docB.Close();

Insert an image on every page

using MuPDF.NET;

Document doc = new Document("input.pdf");
for (int i = 0; i < doc.PageCount; i++)
{
    Page page = doc[i];
    page.InsertImage(page.GetBound(), filename: "watermark.png", overlay: false);
}
doc.Save("watermarked.pdf");
doc.Close();

Extract text with positions

using MuPDF.NET;

Document doc = new Document("input.pdf");
Page page = doc[0];
var blocks = page.GetTextPage().ExtractBLOCKS();
foreach (var block in blocks)
    Console.WriteLine(block);
doc.Close();

OCR a scanned page

using MuPDF.NET;

Document doc = new Document("scanned.pdf");
Page page = doc[0];
TextPage tpage = page.GetTextPageOCR(language: "eng", dpi: 300, full: true);
Console.WriteLine(tpage.ExtractText());
doc.Close();

F#

#r "MuPDF.NET.dll"
let doc   = MuPDF.NET.Document("test.pdf")
let page  = doc.LoadPage(0)
let tpage = page.GetTextPage()
printfn $"{tpage.ExtractText()}"

Visual Basic

Imports MuPDF.NET
Module Program
    Sub Main()
        Dim doc   As Document = New Document("test.pdf")
        Dim page  As Page     = doc.LoadPage(0)
        Dim tpage As TextPage = page.GetTextPage()
        Console.WriteLine(tpage.ExtractText())
    End Sub
End Module

Examples

MuPDF.NET.Examples is a separate repo of small console apps. Each one references MuPDF.NET (and MuPDF.NET.Office where needed) from nuget.org.

git clone https://github.com/ArtifexSoftware/MuPDF.NET.Examples.git
cd MuPDF.NET.Examples
dotnet restore
dotnet run --project MuPDF.NET\01-OpenSave
dotnet run --project MuPDF.NET/01-OpenSave
Folder Contents
MuPDF.NET/ Open/save, pages, render, text, annotations, forms, images, tables, barcodes, encrypt, Markdown / JSON / text, OCR, RAG
MuPDF.NET.Office/ Unlock, open DOCX/HWPX, export PDF / Markdown / JSON
  • Layout samples (33-ToJsonLayout, 34-ToText, 35-ToChunks): Python 3.11+, then dotnet msbuild -t:MuPDFNetSetupLayoutPython.
  • Office samples: set MUPDF_OFFICE_KEY for a full unlock; without a key they open the first 3 pages only.

Batch-run with run-all.cmd / run-all.ps1 / run-all.sh. See the Examples README for the full project list.


API overview

Typical workflow: open → get a page → operate → save → close.

Core classes

Class Purpose
Document Open, create, save, and manipulate documents
Page Text, images, render, annotate, redact
TextPage Structured text (plain, JSON, XML, HTML, dict)
Pixmap Raster image; save as PNG, JPEG, TIFF, and more
Rect / IRect Regions, bounds, clip boxes
Point / Quad Points and quads
Annot Highlights, stamps, shapes, links
Widget Form fields
Font Font loading and metrics
TextWriter Write formatted text onto a page
Outline Table of contents
Barcode Scan and generate barcodes
Story Flow HTML onto pages
Matrix Rotation, scaling, translation

Document

Method Description
new Document(filename) Open from a path
new Document(stream: byte[]) Open from a byte array
doc[n] / doc.LoadPage(n) Page at zero-based index n
doc[(chapter, page)] Page by chapter location
doc.PageCount Number of pages
doc.Save(filename) Save to disk
doc.InsertPdf(src) Insert pages from another PDF
doc.InsertFile(infile) Append a supported file as PDF pages
doc.GetToc() / doc.SetToc(...) Table of contents
doc.SetMetadata(dict) Title, author, and other metadata
doc.Encrypt(...) Password and permissions
doc.RewriteImages(...) Downsample or recompress images
doc.ToMarkdown(...) Convert to Markdown (classic path, or layout when the worker is installed)
doc.ToJson(...) Layout structure as JSON (layout worker)
doc.ToText(...) Convert to plain text (layout worker)
doc.ToChunks(...) Retrieval-ready chunks (layout worker)
doc.GetKeyValues(...) Form field names and values
doc.Close() Release resources

Utils

Member Description
Utils.UseLayout(bool) Enable or disable layout analysis
Utils.LayoutAvailable Whether a layout provider is registered
Utils.LoadAiAsync(...) net8.0 — chunk, embed, and index PDFs for RAG
Utils.MarkdownToPdf(...) Markdown file → PDF
Utils.GetKeyValues(...) Form fields from a Document or path
Utils.LlamaMarkdownReader() LlamaIndex-compatible page loader

Page

Method Description
page.GetTextPage() TextPage for extraction
page.GetTextPageOCR(language, dpi, full) OCR with Tesseract
page.GetText(option) "text", "blocks", "html", "json", "xml"
page.SearchFor(needle) List of Rect matches
page.GetPixmap(...) Render to a Pixmap
page.GetImages() Images on the page
page.InsertImage(rect, filename) Insert an image
page.AddHighlightAnnot(rects) Highlight annotation
page.AddRedactAnnot(rect, fill) Mark a region for redaction
page.ApplyRedactions() Apply redaction marks
page.GetBound() Page bounding Rect

Supported formats

Input: PDF, XPS, EPUB, MOBI, FB2, CBZ, SVG, TXT, JPG/JPEG, PNG, BMP, GIF, TIFF, PNM, PGM, PBM, PPM, PAM, JXR, JPX/JP2, PSD

Output: PDF, PNG, JPEG, TIFF, BMP, SVG, and other raster formats via Pixmap


Building from source

Use NuGet unless you need to change the bindings or the MuPDF engine.

  1. git clone https://github.com/ArtifexSoftware/MuPDF.NET.git
  2. Open MuPDF.NET.sln in Visual Studio 2019 or 2022.
  3. Release / x64, then Build → Build Solution.

Linux: see Getting Started.


Documentation

Resource URL
Product page https://mupdf.com/mupdf-dotnet
Office / HWP https://mupdf.com/mupdf-dotnet/office
API reference https://mupdfnet.readthedocs.io
Getting started https://mupdfnet.readthedocs.io/en/latest/getting-started/index.html
Cookbook https://mupdfnet.readthedocs.io/en/latest/the-basics/index.html
LLM / RAG https://docs.pdf4llm.com/dotnet/getting-started/installation
Sample apps https://github.com/ArtifexSoftware/MuPDF.NET.Examples

License

MuPDF.NET, PyMuPDF, and MuPDF are developed by Artifex Software, Inc.

MuPDF.NET is available under two licences:

The optional layout worker installs and runs PyMuPDF (pymupdf 2.1). That product is licensed separately; see Layout analysis.

Commercial use includes any use that directly or indirectly generates revenue — internal business tooling, SaaS, and enterprise workflows. See LICENSE.md.

About

C# bindings for MuPDF

Topics

Resources

Stars

114 stars

Watchers

10 watching

Forks

Releases

Packages

Used by

Contributors

Languages