modify_layers

Modify state, merge, or strip specific layers

Usage

pdftl <input> modify_layers [action] [target]... output <output> [<option>...]

Details

The modify_layers operation allows you to alter Optional Content Groups (layers) in a PDF. You can permanently merge/strip them, or change their default visibility and behavior.

The command reads a sequence of action-target pairs. If no target is provided after an action, it defaults to affecting “all” layers.

Available Actions

Structural (Permanent):

  • merge: The visual content of the layer is permanently baked into the page. The layer is removed from the PDF’s layer menu.

  • strip: The visual content of the layer is completely deleted from the document, and the layer is removed from the PDF’s layer menu.

State & Behavior (Non-destructive):

  • show / hide: Sets the default visibility when the document is opened.

  • lock / unlock: Prevents/allows the user from toggling the layer in viewers.

  • print / noprint: Overrides behavior to force layer visibility ON or OFF when printing.

  • screen / noscreen: Overrides behavior to force layer visibility ON or OFF on digital displays.

Utility:

  • keep: Used primarily to exclude a specific layer when targeting “all” others.

Note on State vs. Usage: Layer visibility on screen (show/hide) is independent of its visibility when printing. Modifying a usage state (like noprint) without changing its base state will leave its on-screen visibility unchanged.

Target Specifications

  • name=<string>: Sloppy match. Applies the action to all layers with this name.

  • id=<integer>: Strict match. Applies the action to the exact underlying PDF object.

  • all: Explicitly targets all layers.

  • <string>: If no key= prefix is provided, it defaults to a name= match.

Examples

Strip ALL layers from the PDF.

pdftl in.pdf modify_layers strip output out.pdf

Hide all layers by default, except ‘Draft’.

pdftl in.pdf modify_layers hide all show name=Draft output out.pdf

Prevent the ‘Watermark’ layer from showing up on paper.

pdftl in.pdf modify_layers noprint name=Watermark output out.pdf

Tags: layers, modify, merge, strip, visibility, print

Source: pdftl.operations.modify_layers

Read online: https://pdftl.readthedocs.io/en/stable/operations/modify_layers.html

Type: Operation