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.

  • /FontDescriptor property edits from the sidecar’s descriptor block.

  • /CIDToGIDMap restoration, from either "Identity" or an explicit .cid2gid.json sidecar.

  • Type 3 glyph procedure reconstruction (including inline images) from a .charprocs file.

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.

encoding_cmap edits are limited: the only supported change is switching a Type0 font’s /Encoding between /Identity-H and /Identity-V. Any other value written into encoding_cmap is rejected with a warning, and /Encoding is left untouched — there is no general mechanism here for re-encoding into an arbitrary CMap.

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.

For both of these modes, the in-memory binary edit is only ever best-effort: if it can’t be applied (an unresolvable CID-to-GID mapping, no character codes in the font actually matched, or a malformed/unreadable font program), import_fonts still writes the sidecar’s width.pdf values into /Widths or /W directly, so a requested width edit is never silently dropped even when the font program itself couldn’t be patched.

Format-Specific Limitations

When employing squash_font_vectors, be advised that this mode relies on direct, affine coordinate scaling which is only structurally supported for TrueType outline representations (glyf tables). For OpenType-CFF (CFF/CFF2) and classic Adobe Type 1 fonts which do not possess a standard TrueType glyf table, the operation degrades silently to patch_font_metrics mode—meaning the font binary’s internal character metrics will be updated correctly in-memory to prevent layout mismatches, but the visual glyph outline vectors will remain unscaled.

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/stable/operations/import_fonts.html

Type: Operation