HB-SUBSET(1)

📦
version 15.0.0 · 2 versions
, in arch rolling

💅 HB-SUBSET(1) — the subsetter, but make it make sense

okay bestie, so this is hb-subset, a User Commands man page (section 1 of the manual, iykyk), and honestly? it's giving font-surgery main character energy. let's get into it ✨

🌸 NAME 🌸

hb-subset — Subset font to specification.

like, you take a whole font and you're like "girl, we only need these glyphs" and it's iconic about it. 🎀

💖 DESCRIPTION 💖

🦋 Usage:

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

Subset font to specification. that's the whole vibe. you hand it a font, you tell it what you want to keep, it hands you back a smaller font. periodt. 🔥

🧚 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
ngl, when in doubt bestie: just mash --help-all and let it cook 🫶

🎀 Font-face options:

  • --font-file=filename — Set font file-name. this is your input font, the one you're about to glow-up.
  • -y, --face-index=index — Set face index (default: 0). for when your font file is a whole collection and you gotta pick one.
  • --face-loader=loader — Set face loader to use (default: ot). Supported face loaders are: ot/ft. two loaders, pick your fighter 💅
  • --list-face-loaders — List available face loaders and quit. yes it just tells you the loaders and dips.

🍓 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. (so basically "everything except these three, bestie, we don't want them" 😌)
  • --unicodes-file=filename — Specify file to read Unicode codepoints or ranges from
💀 note the pattern: the -= variants subtract from whatever set you already built up. the way that actually works is you build the set first, then subtract. k? 💖

✨ 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. you're the one choosing the new IDs now, main character energy 👑
  • --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". this is the variable-font glow-up right here 🔥

🌈 Subset boolean option:

like, flags. you flip 'em and things happen. 🦋

  • --keep-everything — Keep everything by default. Options after this can override the operation. (order matters, bestie — it's a whole "what comes after counts" situation 💅)
  • --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). so if you don't say anything, it just yeets the font straight at your terminal 🙈

⭐ Application Options:

  • --version — Show version numbers
  • -n, --num-iterations=N — Run subsetter N times (default: 1). literally just do it again and again, N times. for science.

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

🧚 EXIT CODES 🧚

  • 0: Success. slay. 💖
  • 1: Option parsing failed. the options didn't make sense, bestie 😭
  • 2: Failed loading font face. the font said "no" 💀

🌸 ENVIRONMENT 🌸

  • HB_FACE_LOADER=face-loader — Overrides the default face loader.

that's it, one env var, she's lowkey iconic like that ✨

🎀 SEE ALSO 🎀

hb-view(1), hb-shape(1), hb-raster(1), hb-vector(1), hb-subset(1), hb-info(1)

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

okay and finally, the sign-off 💅 — this whole thing is HarfBuzz 15.0.0, dated October 2026, and it lives in section 1 (User Commands) of the manual. go forth and subset, bestie, you're gonna ate 🦋👑

📦 where this page comes from