---
name: "hb-subset"
section: "1"
platform: "linux"
package: "harfbuzz-utils"
version: "15.0.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/hb-subset"
---

# hb-subset(1)

Subset font to specification.

## NAME

hb-subset - Subset font to specification.

## DESCRIPTION

### Usage:

-

  hb-subset \[OPTION???\] \[FONT-FILE\] \[TEXT\]

Subset font to specification.

### Help Options:

- **-h**, **--help**

  Show help options

- **--help-all**

  Show all help options

- **--help-face**

  Options for the font face

- **--help-subset-glyphset**

  Subsetting glyph-set options

- **--help-subset-other**

  Subsetting other options

- **--help-subset-flags**

  Subsetting boolean options

- **--help-output**

  Options for the destination & form of the output

### Font-face options:

- **--font-file**=*filename*

  Set font file-name

- **-y**, **--face-index**=*index*

  Set face index (default: 0)

- **--face-loader**=*loader*

  Set face loader to use (default: ot)

-

  Supported face loaders are: ot/ft

- **--list-face-loaders**

  List available face loaders and quit

### Subset glyph-set option:

- **-g**, **--gids**=*list* of glyph indices/ranges or \*

  Specify glyph IDs or ranges to include in the subset. Use **--gids-=**... to subtract codepoints from the current set.

- **--gids-file**=*filename*

  Specify file to read glyph IDs or ranges from

- **--glyphs**=*list* of glyph names or \*

  Specify glyph names to include in the subset. Use **--glyphs-=**... to subtract glyphs from the current set.

- **--glyphs-file**=*filename*

  Specify file to read glyph names from

- **-t**, **--text**=*string*

  Specify text to include in the subset. Use **--text-=**... to subtract codepoints from the current set.

- **--text-file**=*filename*

  Specify file to read text from

- **-u**, **--unicodes**=*list* of hex numbers/ranges or \*

  Specify Unicode codepoints or ranges to include in the subset. Use \* to include all codepoints. **--unicodes-=**... can be used to subtract codepoints from the current set. For example: **--unicodes=**\* **--unicodes-**=*41*,42,43 would create a subset with all codepoints except for 41, 42, 43.

- **--unicodes-file**=*filename*

  Specify file to read Unicode codepoints or ranges from

### Subset other option:

- **--gid-map**=*List* of pairs old\_gid1:new\_gid1,old\_gid2:new\_gid2,...

  Specify a glyph mapping to use, any unmapped gids will be automatically assigned.

- **--name-IDs**=*list* of int numbers or \*

  Subset specified nameids. Use **--name-IDs-=**... to subtract from the current set.

- **--name-languages**=*list* of int numbers or \*

  Subset nameRecords with specified language IDs. Use **--name-languages-=**... to subtract from the current set.

- **--layout-features**=*list* of string table tags or \*

  Specify set of layout feature tags that will be preserved. Use **--layout-features-=**... to subtract from the current set.

- **--layout-scripts**=*list* of string table tags or \*

  Specify set of layout script tags that will be preserved. Use **--layout-scripts-=**... to subtract from the current set.

- **--drop-tables**=*list* of string table tags or \*

  Drop the specified tables. Use **--drop-tables-=**... to subtract from the current set.

- **--variations**=*list* of comma separated axis-locations.

  (Partially\|Fully) Instantiate a variable font. A location consists of the tag of a variation axis, followed by '=', followed by a number or the literal string 'drop'. For example: **--variations=**"wdth=100 wght=200" or **--variations=**"wdth=drop"

### Subset boolean option:

- **--keep-everything**

  Keep everything by default. Options after this can override the operation.

- **--no-hinting**

  Whether to drop hints

- **--retain-gids**

  If set don't renumber glyph ids in the subset.

- **--desubroutinize**

  Remove CFF/CFF2 use of subroutines

- **--downgrade-cff2**

  Convert instantiated variable fonts from CFF2 to CFF1

- **--cff-identity-charset**

  Emit identity CFF charset (CID = new GID) for CID-keyed CFF

- **--name-legacy**

  Keep legacy (non-Unicode) 'name' table entries

- **--set-overlaps-flag**

  Set the overlaps flag on each glyph.

- **--notdef-outline**

  Keep the outline of '.notdef' glyph

- **--no-prune-unicode-ranges**

  Don't change the 'OS/2 ulUnicodeRange\*' bits.

- **--no-layout-closure**

  Don't perform glyph closure for layout substitution (GSUB).

- **--no-bidi-closure**

  Don't perform bidi closure (adding mirrored variants) for input codepoints.

- **--glyph-names**

  Keep PS glyph names in TT-flavored fonts.

- **--passthrough-tables**

  Do not drop tables that the tool does not know how to subset.

- **--preprocess**

  If set preprocesses the face with the add accelerator option before actually subsetting.

- **--optimize**

  Perform IUP delta optimization on the resulting gvar table's deltas

### Output destination & format options:

- **-o**, **--output-file**=*filename*

  Set output file-name (default: stdout)

### Application Options:

- **--version**

  Show version numbers

- **-n**, **--num-iterations**=*N*

  Run subsetter N times (default: 1)

Subsets font file to a specified set of glyphs, Unicode codepoints, or text, design-space limiting, and other reductions.

## EXIT CODES

-

  0: Success.

-

  1: Option parsing failed.

-

  2: Failed loading font face.

## ENVIRONMENT

-

  HB\_FACE\_LOADER=face-loader; Overrides the default face loader.

## SEE ALSO

-

  [hb-view(1)](/hb-view/1.md), [hb-shape(1)](/hb-shape/1.md), [hb-raster(1)](/hb-raster/1.md), [hb-vector(1)](/hb-vector/1.md), [hb-subset(1)](/hb-subset/1.md), [hb-info(1)](/hb-info/1.md)

Find more information or report bugs at \<https://github.com/harfbuzz/harfbuzz\>