The Best PDF Inspector Tools for Developers

If you have ever opened a PDF in a hex editor at 2am trying to work out why a font is missing or why a page renders blank, you already know why PDF inspector tools exist. A PDF is a binary file with a stream-based command language inside it, and reading the spec in your head while staring at raw bytes is not a productive way to debug rendering bugs.

This post compares four PDF inspector tools that developers actually use:

• JPedal Inspector
• iText RUPS
• Apache PDFBox PDFDebugger
• Nutrient PDF Inspector

We cover what each one does well, where each one falls short, and which one to reach for depending on what you are trying to debug. JPedal is our own product, so we have called out where the others beat it as well as where it beats them.

What is a PDF inspector?

A PDF inspector is a tool that lets a developer browse the internal structure of a PDF file: its COS object tree, its cross-reference table (XRef), its content streams, fonts, images, annotations, and metadata.

PDF inspectors are used to diagnose rendering failures, fix corrupt files, verify that a PDF generator is producing valid output, and learn how the PDF format works.

A reliable PDF inspector reads the file the same way a renderer would, which means it surfaces the file as a renderer sees it, not as a generic binary file. That is the difference between a PDF inspector and a hex editor.

Quick Comparison

The table below gives a nice summary of the capabilities, features and price of PDF inspectors available for developers:

JPedal Inspector

JPedal Inspector is a free download from IDRsolutions. It ships as a standalone launcher.jar and is also bundled inside the full JPedal Java PDF Library.

JPedal Inspector exists as a separate tool because JPedal customers needed a way to diagnose rendering bugs in customer PDFs without writing throwaway Java code, and other developers had the same problem.

java -jar launcher.jar

Single-step debugging with breakpoints

Every PDF page is a PostScript-derived command stream. JPedal Inspector lets you pause decoding at any command, step forward one command at a time, and set breakpoints on specific commands.

When a page renders incorrectly, you can step until the rendering goes wrong and identify the exact command that caused the problem. This is the only free Java PDF inspector that does this. The full workflow is documented in our PDF debugger walkthrough on our blog.

Cross-reference stream viewer that respects /W widths

PDF 1.5 introduced compressed XRef streams to reduce file size. Each entry in an XRef stream has a width defined by the file’s /W array, so a stream with /W [1 2 1] has 1-byte type, 2-byte offset, and 1-byte generation columns. Most inspectors display the raw stream and leave you to count bytes.

JPedal Inspector renders the columns at their actual widths. We wrote more about why XRef streams need a special viewer in our XRef stream improvements post.

Syntax highlighting of raw PDF object bytes

When you open an object, tokens are coloured by type: names, strings, arrays, dictionaries keys, dictionary values, object references.

A step-by-step walkthrough of all three features is in our Inspector documentation.

iText RUPS

RUPS stands for “Reading and Updating PDF Syntax” and is built on iText 7 Core. The 26.03 release introduced calendar versioning (YY.MM) decoupled from the iText library version, and added ASN.1 data structure support for inspecting digital signatures, timestamps, certificates, CRLs, and OCSP responses.

For digital signature debugging, RUPS is the strongest tool in this comparison. If you are working on PAdES signatures or trying to figure out why a CMS signature blob is malformed, RUPS is the answer.

It also has a structure tree viewer that shows text inside marked content items, which is useful for tagged PDF accessibility work.

RUPS can open files in read-write mode and modify objects in place. It also has a “debug mode” that tries to open invalid files plain iText refuses to parse, though it is honest about the fact that some files are too broken to recover.

The licensing is AGPL or commercial. If your project is not AGPL-compatible and you want to use RUPS as part of a paid product, you need an iText commercial license. For personal debugging the AGPL terms are fine.

What RUPS does not do: step through the content stream command by command, set breakpoints, show XRef streams with /W-aware column widths, or syntax-highlight raw object bytes.

Apache PDFBox PDFDebugger

PDFDebugger ships with the Apache PDFBox library. Launch it from the PDFBox application jar:

java -jar pdfbox-app-3.y.z.jar debug input.pdf

In PDFBox 2.x the command was PDFDebugger. PDFBox 3.0 rewrote the CLI to use lowercase commands and options/flags consistently, per the 3.0 migration guide.

PDFDebugger’s strongest feature is its text extraction debugging. It shows glyph metrics used by text extraction, text-stripper text positions, text-stripper beads, approximate text bounds, and glyph bounds. If you are debugging why PDFTextStripper is producing weird output, this is the tool to use.

It also handles object tree browsing, XRef table viewing, and page rendering with image extraction. The licence is Apache 2.0, which means no commercial restrictions and no licence fee.

Nutrient PDF Inspector

Nutrient’s PDF Inspector is a macOS-only app from the Mac App Store. The company rebranded from PSPDFKit to Nutrient in October 2024, though the App Store listing still shows the developer as “PSPDFKit GmbH” and the app is named PDF Inspector.

Its differentiator is object editing. You can add and remove PDF objects (Number, String, Name, Boolean, Reference, Dictionary, Stream) and edit content streams in either text or hex format with transparent decompression.

If you need to manually patch a PDF object to test a fix, this is the easiest tool for the job. RUPS can also edit objects but the editing UX is less polished.

Which tool for which bug?

What PDF Inspector best fits your need will be decided on a number of factors, some of which are considered in the following table:

Frequently Asked Questions

How do I debug a PDF rendering bug?

Open the file in JPedal Inspector, navigate to the page that renders incorrectly, and use the limit decode slider to step through the content stream one command at a time. Set a breakpoint on the command where the rendering goes wrong, then inspect the graphics state and the operands of that command. This is faster than reading the raw stream because the inspector resolves text and image references for you.

What is the difference between a PDF inspector and a PDF editor?

A PDF inspector shows you the internal structure of a PDF: objects, streams, the XRef table, fonts, and content commands. It is a diagnostic tool. A PDF editor changes the visible content of a PDF: text, images, form fields, and page order. Most PDF inspectors are read-only or near read-only, and most PDF editors hide the internal structure from you. Nutrient PDF Inspector and iText RUPS sit in between because they allow low-level object editing.

Can PDF Inspectors open corrupt PDF files?

Partially. JPedal Inspector handles many malformed files because JPedal itself has been hardened against more than twenty years of broken customer PDFs. RUPS has a debug mode that opens files plain iText refuses. PDFBox is reasonably tolerant but will fail on some files. Nutrient is generally robust on Mac. No inspector opens every broken file, since some are simply too damaged to parse.

//Convenience static method (see class for additional options)
ExtractClippedImages.writeAllClippedImagesToDir("inputFileOrDirectory", "outputDir", "outputImageFormat", new String[] {"imageHeightAsFloat", "subDirectoryForHeight"});

final PdfManipulator pdf = new PdfManipulator();
pdf.loadDocument(new File("inputFile.pdf"));
pdf.addPage(1, PaperSize.A4_LANDSCAPE);
pdf.addText(1, "Hello World", 10, 10, BaseFont.HelveticaBold, 12, 1, 0.3f, 0.2f);
pdf.addImage(1, new BufferedImage(), new float[] {0, 0, 100, 100});
pdf.rotatePage(1, 90);
pdf.apply();
pdf.writeDocument(new File("outputFile.pdf"));

Viewer viewer = new Viewer();
viewer.setupViewer();
viewer.executeCommand(ViewerCommands.OPENFILE, "pdfFile.pdf");

//Convenience static method (see class for additional options)
ExtractTextAsWordList.writeAllWordlistsToDir("inputFileOrDirectory", "outputDir", -1);

PdfMerge.mergeFiles(new File("inputFile1.pdf"), new File("inputFile2.pdf"), new File("outputFile.pdf"));

PdfManipulator.splitInHalf(new File("inputFile.pdf"), new File("outputFolder"), pageToSplitAt);

PrintPdfPages print = new PrintPdfPages("C:/pdfs/mypdf.pdf");

if (print.openPDFFile()) {
    print.printAllPages("Printer Name");
}

//Convenience static method (see class for additional options)
ExtractClippedImages.writeAllClippedImagesToDir("inputFileOrDirectory", "outputDir", "outputImageFormat", new String[] {"imageHeightAsFloat", "subDirectoryForHeight"});

//Convenience static method (see class for additional options)
ArrayList resultsForPages = FindTextInRectangle.findTextOnAllPages("/path/to/file.pdf", "textToFind");

java -jar jpedal.jar --inspect "inputFile.pdf"

PdfSigner.signPdf(
        "inputFile.pdf",
        "outputFile.pdf",
        "keystorePassword",
        "keystoreFile.p12",
        "signerName",
        "signerLocation",
        "signingReason",
        ACCESS_PERMISSION.P1
);