Cross-platform PDF manipulation for Dart & Flutter. Merge, split, render, extract, search, sign, encrypt, validate, convert, or build from scratch. Every operation runs off the main thread and streams large files in chunks. Any of it can be cancelled mid-flight.

like it? a ⭐ star or 👍 like is the entire marketing budget. Bugs & features →

Coming from the old Android-only package? everything changed, but the migration guide has the before/after for every call.

Install

Add the dependency

dependencies:
  pdf_manipulator: ^2.1.1

Native

Nothing to do. On iOS, Android, macOS, Windows, and Linux, the build hook downloads the right binary on first build.

Web

Web can't auto-download native assets, so run setup once. It fetches the prebuilt WASM engine. Run it again after any pub upgrade, since the asset is tied to the package version:

flutter pub run pdf_manipulator:setup

Pin the version, too, so a pub upgrade can't bump it behind your back and leave that fetched asset stale:

pdf_manipulator: 2.1.1  # exact version

flutter pub run pdf_manipulator:setup                  # web (default)
flutter pub run pdf_manipulator:setup <target>         # web|android|ios|macos|linux|windows
flutter pub run pdf_manipulator:setup --force <target> # re-resolve (debugging)

Quick start

Merge two PDFs

Merge two PDFs, using bytes in memory (works on web too):

import 'package:pdf_manipulator/pdf_manipulator.dart';

// one Pdf instance, reused everywhere
final pdf = Pdf();

// your two PDFs, as sources
final firstPdf = MemorySource(firstPdfBytes);
final secondPdf = MemorySource(secondPdfBytes);

// where the merged PDF lands
final output = MemorySink();

// combine the two into the output
await pdf.merge([firstPdf, secondPdf], output);

// take the merged bytes, then dispose it
final merged = output.takeBytes();
await pdf.dispose();

On mobile or desktop, point the same program at files; only the sources, sink, and import change:

import 'package:pdf_manipulator/pdf_manipulator.dart';
import 'package:pdf_manipulator/io.dart'; // adds FileSource / FileSink

final pdf = Pdf();

// read the two PDFs straight from disk
final firstPdf = FileSource(File('first.pdf'));
final secondPdf = FileSource(File('second.pdf'));

// write the result straight to a file
final output = await FileSink.create(File('merged.pdf'));

// the merge call is identical
await pdf.merge([firstPdf, secondPdf], output);

// flush the file, then dispose it
await output.close();
await pdf.dispose();

That's the shape of every edit: source in, sink out. Watermark, compress, split, sign are the same shape, a different verb. Reading is the other shape: open a document and query it, no sink needed. See Usage for the full menu of both.

Cancellation

Long job the user no longer needs? You can stop it. Every operation is a PdfTask: an ordinary Future you await, plus a cancel() button.

Keep the task in a variable: await it as usual, and cancel() it to stop early, from a Cancel button or your widget's dispose().

// run it and await it — your normal code
final task = pdf.merge([firstPdf, secondPdf], output); // starts running
try {
  await task;
  final merged = output.takeBytes(); // success
} on PdfCancelled {
  // cancelled — the Pdf and everything else keep working
}

// stop it — from a Cancel button, or your widget's dispose()
task.cancel(); // the await above now throws PdfCancelled

Three rules and you're safe:

• The cancel() call never throws — it sends a stop request and returns. No try/catch needed; it's safe to call twice, and a no-op once the task is done.
• PdfCancelled only appears when you await the task — never a half-finished result. That's the spot to wrap in try/catch.
• Never await the task? Nothing to handle — cancel it and move on, no error, no crash.

To stop everything, pdf.dispose() cancels every operation and returns immediately; it never waits for in-flight work to drain.

final pdf = Pdf(config: PdfConfig(maxLanes: 8)); // default: max(2, cores ÷ 2)

Sources & sinks

Every operation reads from a source and writes to a sink. You've already used the built-ins: MemorySource/MemorySink for bytes, FileSource/FileSink for files. Write your own for anything else (a server, a database, a Blob).

abstract interface class DataSource {
  int get length; // how big are you?
  FutureOr<Uint8List> readAt(int offset, int count); // count bytes from offset
}

abstract interface class DataSink {
  FutureOr<void> write(Uint8List chunk); // here's a chunk of output
}

import 'package:http/http.dart' as http;

class UrlSource implements DataSource {
  UrlSource(this.uri, this.length); // length from a HEAD request
  final Uri uri;
  @override
  final int length;

  @override
  Future<Uint8List> readAt(int offset, int count) async {
    final res = await http.get(uri,
        headers: {'range': 'bytes=$offset-${offset + count - 1}'});
    return res.bodyBytes;
  }
}

// then use it exactly like any other source
final doc = await pdf.open(UrlSource(uri, contentLength));

import 'package:web/web.dart' as web;

class BlobSource implements DataSource {
  BlobSource(this._blob) : length = _blob.size;
  final web.Blob _blob;
  @override
  final int length;

  @override
  Future<Uint8List> readAt(int offset, int count) async {
    final slice = _blob.slice(offset, offset + count);
    final bytes = await slice.arrayBuffer().toDart;
    return bytes.asUint8List();
  }
}

Usage

Everything goes through one of four doors. Pick the one that fits what you're doing. Highlights below; every method and full signature lives in the API reference.

One-shot operations

A single change: call it straight on pdf, source in, sink out:

await pdf.watermark(source, output,
    text: 'CONFIDENTIAL',
    style: PdfWatermarkStyle(opacity: 0.2, fontSize: 60));

await pdf.compress(source, output, imageQuality: 75);

await pdf.encrypt(source, output,
    encryption: PdfEncryptionConfig(
      ownerPassword: 'secret',
      algorithm: PdfEncryptionAlgorithm.aes256,
    ));

await pdf.split(source, (i) => MemorySink(), every: 5);

The full one-shot set, all the same shape: merge, split / splitBySize / splitByBookmarks, extractPages, deletePages, reorderPages, movePage, rotatePages / rotateAllPages, addStamp / addImageStamp, flattenForms, applyRedactions, embedFile, eraseRegions, decrypt, sign, convertTo (DOCX/PPTX/XLSX), convertToPdf, convertToPdfA, imagesToPdf.

Doing several of these to the same PDF? Use the editor (below); it parses once instead of re-parsing per call.

Read a document

pdf.open gives you a document to query as much as you like, then dispose:

final doc = await pdf.open(source);
print('${doc.pageCount} pages · encrypted: ${doc.isEncrypted}');

final text = await doc.extract(pages: PdfPages.all());
final hits = await doc.search(query: 'revenue', pages: PdfPages.all());

await for (final page in doc.render(
    pages: PdfPages.all(), size: PdfRenderSize.thumbnail(200))) {
  // page.width, page.height, page.data — PNG-encoded bytes; decode to read pixels
}

await doc.dispose();

Also on the document: extract (plain / markdown / html), extractImages, getSignatures / verifySignatures, validatePdfA / validatePdfUa, classifyPage / classifyDocument, planSplitByBookmarks, plus metadata getters (title, author, version, isTagged).

Edit a document

pdf.edit is for many changes to one PDF. It parses once, applies everything in memory, and writes once on save:

final editor = await pdf.edit(source);

await editor.setTitle('Q4 Report');
await editor.mergeFrom(appendix);
await editor.deletePage(4);
await editor.addWatermark(0, 'FINAL', style: PdfWatermarkStyle(opacity: 0.15));
await editor.optimizeImages(quality: 70);

await editor.save(output); // see save options below
await editor.dispose();

Also on the editor: selectPages, rotatePage / rotateAllPages, addStamp / addImageStamp, embedFile, eraseRegions, cropMargins, resizeImage, flattenForms / flattenAllAnnotations, setFormFieldValue, unembedStandardFonts, convertToPdfA, scrubMetadata, and metadata get/set.

Save options:

• PdfSaveOptions.fullRewrite() — default; recompresses and drops unused objects.
• PdfSaveOptions.fullRewrite(encryption: ...) — encrypt on save (or PdfEncryption.remove() to strip it).
• PdfSaveOptions.incremental() — appends changes; faster, larger file.

Redaction is a mark-then-apply lifecycle (the content is removed, not just hidden):

editor.addRedaction(0, PdfRect(x: 72, y: 700, width: 200, height: 20));
print(await editor.redactionCount(0)); // pending marks on this page
await editor.applyRedactions(); // gone for good

Build from scratch

pdf.build hands you an empty PDF; add pages, then content:

final builder = await pdf.build();
await builder.setTitle('Invoice #1042');

final page = await builder.addA4Page();
await page.heading(1, 'Invoice');
await page.paragraph('Thank you for your purchase.');
await page.textField('notes', PdfRect(x: 50, y: 400, width: 300, height: 100));
await page.linkUrl('https://example.com');

await builder.save(output);
await builder.dispose();

Pages: addA4Page / addLetterPage / addPage (custom size). Content: text, heading, paragraph, space, image, columns, footnote, watermark; form fields (textField, checkbox, radioGroup, comboBox, pushButton, signatureField) with Acrobat JS actions (fieldFormat, fieldValidate, fieldCalculate, fieldKeystroke); links (linkUrl, linkPage).

Error handling

Every failure is a typed subclass of PdfError: no string matching, no PlatformException. Catch the cases you handle specially; let the rest fall to a catch-all. Each error carries a human-readable message.

try {
  final doc = await pdf.open(source);
  // ... use the document, then doc.dispose()
} on PdfPasswordRequired {
  // encrypted — retry with pdf.open(source, password: '...')
} on PdfWrongPassword {
  // wrong password — ask the user again
} on PdfCorrupted catch (e) {
  print('Not a valid PDF: ${e.message}');
} on PdfError catch (e) {
  // anything else — I/O failure, unsupported feature, page out of range...
  print(e.message);
}

PdfError is sealed, so you can also catch (e) once and switch over it, and the compiler flags any case you haven't handled. PdfCancelled is part of the same hierarchy (the one Cancellation throws).

Platform support

Every platform Flutter runs on, one API. Native platforms run a Rust core; web runs that same core compiled to WASM.

Browser support

Minimum versions, with no special setup:

The engine compiles to WASM and runs in isolated Web Workers, so your UI thread never touches PDF work. No jank, even on large files. (These floors can go further back with two extra headers; see Web I/O modes.)

Web I/O modes

On web you don't configure anything; the package auto-detects the best mode the browser supports and uses it. Everything works regardless of mode; the only thing that varies is how fast it reads large files.

Under the hood the modes differ in how the WASM engine gets your bytes: the top two stream them on demand, while the fallback copies the whole file into private browser storage first (works everywhere, just a slower first byte).

final pdf = Pdf(config: PdfConfig(webIoMode: PdfIoMode.atomics)); // pin a mode
final mode = await pdf.ensureInitialized(); // or just check

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

flutter run -d chrome --cross-origin-isolation

Not in the box

A tiny wishlist — what the shipped package doesn't do yet, and what to grab in the meantime. For the full engine-vs-shipped picture, see the capability roadmap.

• A viewer to display PDFs. This is a manipulation library, not a UI widget. To put a PDF on screen, use pdfx or flutter_pdfview. It pairs well: pre-process here (merge, decrypt, watermark), display there. (It does render pages to image bytes via doc.render(...) if you'd rather draw your own surface.)
• OCR and table extraction. extract and search read the text already in a PDF, so a scanned page (just an image) comes back empty, and clean rows-and-columns is a separate problem. The engine has both (a PaddleOCR pipeline and ML table detection); the default build leaves them out so it doesn't pull the ONNX runtime and ~12 MB of models into every install. An opt-in build is on the roadmap; until then, run them externally (Tesseract, Camelot, or a cloud API) and feed the result back. Want them first-party? Open an issue; it's how we gauge demand.

Docs

The README covers the everyday stuff. wanna go deeper?

License

MIT. See LICENSE.