Optimize the PDF file by removing unused resources

View as MarkdownMarkdown

Set up your AI agent

Give your coding agent live access to the GroupDocs documentation and API reference through the GroupDocs Docs MCP server — no install, no API key. Learn more

claude mcp add --transport http groupdocs-docs https://docs.groupdocs.com/mcp

Also process documents locally

The GroupDocs.Viewer MCP server lets your agent work with files on your machine; they are never uploaded. It needs the .NET 10 SDK or Docker.

claude mcp add groupdocs-viewer -- dnx GroupDocs.Viewer.Mcp --yes
Folders, licensing and more →

In some cases PDF documents may contain different resources, which are unused, which means they are not accessible and visible when viewing the document in any PDF viewer. Starting from version 24.9 the GroupDocs.Viewer is able to remove such unused resources using two new public properties of the boolean type: remove_unused_objects and remove_unused_streams, both of which are located in the PdfOptimizationOptions class. By default both options are disabled (False), so the GroupDocs.Viewer will not apply this optimization.

The two options remove two different kinds of unused data.

Unused objects

PDF document consists of PDF objects. Every object has its number (ID) and may belong to one of the following types: name, string, number, boolean, null object, dictionary, array (forms PDF document structure), and stream (raw binary data). Objects may be referenced from other objects, for example, a dictionary or array may contain references to other objects. These references unite all parts of the PDF document and form a PDF document structure. Stream objects contain binary data, and the size of these data may be large. For example, images or fonts are stored as stream objects. After some manipulations with the document, some streams may be “orphaned” i.e. they may not have any reference to them. For example, the old image was replaced with the new one, but the binary data of the old image was not removed. In other words, the stream does not belong anymore to the document logically but still contained in the document physically. For removing such orphaned objects the remove_unused_objects property exists — it finds orphaned objects in the document and removes them, this can help to decrease the document size of such objects found.

Unused streams

Every document page has its Resources dictionary which contains data like images, fonts, etc. which are used in the page contents. Resources are referenced by their names in the dictionary, for example, the page may contain the operator to draw the image with the name “Image12” on the particular place of the page. In some cases, the resource may become unused, for example, the image was removed from the page contents but left in page resources, or the page was extracted from the document but its resources still contain common resources of the document. Resource became “orphaned”, note that this is another situation than the unused objects above, because the object is still referenced from the resources dictionary of the page, but the resource is never used by the page (its name never used in page contents). remove_unused_streams property, when enabled, finds and removes these unnecessary resources. Since after this process removed resource stream objects became not linked with document structure, remove_unused_objects is applied too when remove_unused_streams is enabled.

Remove unused objects and streams

Here is an example, where both options are applied to the same input PDF file, so Viewer produces two output PDF files with distinct options applied.

from groupdocs.viewer import Viewer
from groupdocs.viewer.options import PdfViewOptions, PdfOptimizationOptions

def remove_unused_resources():

    view_options_1 = PdfViewOptions("remove_unused_resources/removed_unused_objects.pdf")
    view_options_1.pdf_optimization_options = PdfOptimizationOptions()
    view_options_1.pdf_optimization_options.remove_unused_objects = True

    view_options_2 = PdfViewOptions("remove_unused_resources/removed_unused_streams.pdf")
    view_options_2.pdf_optimization_options = PdfOptimizationOptions()
    view_options_2.pdf_optimization_options.remove_unused_streams = True

    with Viewer("sample.pdf") as viewer:
        viewer.view(view_options_1)
        viewer.view(view_options_2)

if __name__ == "__main__":
    remove_unused_resources()

sample.pdf is the sample file used in this example. Click here to download it.

remove_unused_resources/removed_unused_objects.pdf (890 KB)
remove_unused_resources/removed_unused_streams.pdf (542 KB)

Download full output

How much it saves

As it is explained above, the effectiveness of the described optimizations depends solely on the specific PDF file — if it has no “orphaned” objects or streams, then these optimizations will do nothing, they only increase the document processing time. However, in some cases they can reduce the document size significantly, even several times.

The sample file of this example is a catalog extract that was edited in place, so it has both kinds of orphans: four photos that its first page lists but never draws (unused streams), and the objects of a deleted page (unused objects). Rendered with each option, it gives these sizes:

FileOriginal size, bytesremove_unused_objects, bytesremove_unused_streams, bytes
sample.pdf1 053 186911 481554 937