#  `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`](<export_fonts.md>)) 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](https://pdftl.readthedocs.io/en/stable/operations/import_fonts.html)*

*Type: Operation*