import_fonts

Import edited fonts from a directory using a JSON manifest

Usage

pdftl <input> import_fonts <dir> [manifest=<manifest.json>] output <out.pdf>

Details

The import_fonts operation reads a JSON manifest (generated by export_fonts) and overwrites the corresponding internal PDF font structures with the edited assets from a directory.

It automatically handles:

  • Binary Font stream injection if MD5 hashes differ (safe skip on unmodified files).

  • Character metrics updates based on the ‘width_sync_mode’ parameter.

  • Re-compilation of sidecar ToUnicode JSON maps back to compliant PostScript CMaps.

If both .json and .ps files exist for a given font’s /ToUnicode map, an error is raised to prevent ambiguity. The user must delete or rename one of them first.

Width Sync Modes

Each font’s unified JSON sidecar (font_{obj_id}_{gen_id}_{name}.json) has a top-level width_sync_mode field, defaulting to auto on export. This controls how import_fonts reconciles the PDF’s /Widths (or /W for CID fonts) with any edits:

  • auto (default): Reads the true metrics out of the edited font binary (if its MD5 changed since export) and writes those into the PDF. If the binary is unchanged or unreadable, falls back to manual behavior using any width.pdf values present in the sidecar mappings.

  • manual: Writes the width.pdf values from the sidecar mappings directly into the PDF, ignoring the font binary.

  • patch_font_metrics: Dynamically patches the font binary’s horizontal metrics table in-memory to match the sidecar’s width.pdf values, and writes the patched stream directly into the PDF (leaving workspace files untouched).

  • squash_font_vectors: Dynamically rescales the font binary’s glyph outlines in-memory to visually fit the sidecar’s width.pdf values, and writes the squashed stream directly into the PDF (leaving workspace files untouched).

  • preserve: Leaves the PDF’s existing /Widths untouched entirely.

patch_font_metrics and squash_font_vectors require the embedded font file to be present in the directory; without it, no width sync occurs for that font.

Examples

Import edited fonts from ‘my_fonts/’ and save.

pdftl in.pdf import_fonts my_fonts output out.pdf

Tags: in_place, fonts, import, replace

Source: pdftl.operations.export_import_fonts

Read online: https://pdftl.readthedocs.io/en/latest/operations/import_fonts.html

Type: Operation