HB-SHAPE(1) User Commands HB-SHAPE(1)
hb-shape - manual page for hb-shape 11.3.3
Usage:
hb-shape [OPTION?] [FONT-FILE] [TEXT]
Shape text with given font.
Help Options:
-h, --help
Show help options
--help-all
Show all help options
--help-face
Options for the font face
--help-font
Options for the font instance
--help-variations
Options for font variations used
--help-text
Options for the input text
--help-text-context
Options for the input context text
--help-shape
Options for the shaping process
--help-features
Options for font features used
--help-output
Options for the destination & form of the output
--help-output-syntax
Options for the syntax 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
Font-instance options:
--font-size=1/2 integers or 'upem'
Font size (default: upem)
--font-ppem=1/2 integers
Set x,y pixels per EM (default: 0; disabled)
--font-ptem=point-size
Set font point-size (default: 0; disabled)
--font-bold=1/2 numbers; eg. 0.05
Set synthetic bold (default: 0)
--font-grade=1/2 numbers; eg. 0.05
Set synthetic grade (default: 0)
--font-slant=slant ratio; eg. 0.2
Set synthetic slant (default: 0)
--font-funcs=impl
Set font functions implementation to use (default: ot)
Supported font function implementations are: ot/ft
--list-font-funcs
List available font functions and quit
--ft-load-flags=integer
Set FreeType load-flags (default: 2)
Variations options:
--named-instance=index
Set named-instance index (default: none)
--variations=list
Comma-separated list of font variations
Variations are set globally. The format for specifying
variation settings follows. All valid CSS
font-variation-settings values other than 'normal' and
'inherited' are also accepted, though, not documented below.
The format is a tag, optionally followed by an equals sign,
followed by a number. For example:
"wght=500" "slnt=-7.5"
Text options:
If no text is provided, standard input is used for input.
--text=string
Set input text
--text-file=filename
Set input text file-name
-u, --unicodes=list of hex numbers
Set input Unicode codepoints
--single-par
Treat text as single paragraph
Textual context options:
--text-before=string
Set text context before each line
--text-after=string
Set text context after each line
--unicodes-before=list of hex numbers
Set Unicode codepoints context before each line
--unicodes-after=list of hex numbers
Set Unicode codepoints context after each line
Shape options:
--shapers=comma-separated list
Set shapers to use (default: graphite2)
Supported shapers are: graphite2/ot/fallback
--list-shapers
List available shapers and quit
--direction=ltr/rtl/ttb/btt
Set text direction (default: auto)
--language=BCP 47 tag
Set text language (default: $LANG)
--script=ISO-15924 tag
Set text script (default: auto)
--bot Treat text as beginning-of-paragraph
--eot Treat text as end-of-paragraph
--preserve-default-ignorables
Preserve Default-Ignorable characters
--remove-default-ignorables
Remove Default-Ignorable characters
--invisible-glyph
Glyph value to replace Default-Ignorables with
--not-found-glyph
Glyph value to replace not-found characters with
--not-found-variation-selector-glyph
Glyph value to replace not-found variation-selector characters
with
--utf8-clusters
Use UTF8 byte indices, not char indices
--cluster-level=0/1/2/3
Cluster merging level (default: 0)
--normalize-glyphs
Rearrange glyph clusters in nominal order
--unsafe-to-concat
Produce unsafe-to-concat glyph flag
--safe-to-insert-tatweel
Produce safe-to-insert-tatweel glyph flag
--glyphs
Interpret input as glyph string
--verify
Perform sanity checks on shaping results
Features options:
--features=list
Comma-separated list of font features
Features can be enabled or disabled, either globally or
limited to specific character ranges. The format for
specifying feature settings follows. All valid CSS
font-feature-settings values other than 'normal' and the
global values are also accepted, though not documented below.
CSS string escapes are not supported. The range indices refer
to the positions between Unicode characters, unless the
--utf8-clusters is provided, in which case range indices refer
to UTF-8 byte indices. The position before the first character
is always 0.
The format is Python-esque.
Here is how it all works:
Syntax:
Value: Start: End:
Setting value:
"kern" 1 0 ? # Turn feature on
"+kern"
1 0 ? # Turn feature on
"-kern"
0 0 ? # Turn feature off
"kern=0"
0 0 ? # Turn feature off
"kern=1"
1 0 ? # Turn feature on
"aalt=2"
2 0 ? # Choose 2nd alternate
Setting index:
"kern[]"
1 0 ? # Turn feature on
"kern[:]"
1 0 ? # Turn feature on
"kern[5:]"
1 5 ? # Turn feature on, partial
"kern[:5]"
1 0 5 # Turn feature on, partial
"kern[3:5]"
1 3 5 # Turn feature on, range
"kern[3]"
1 3 3+1 # Turn feature on, single char
Mixing it all:
"aalt[3:5]=2" 2
3 5 # Turn 2nd alternate on for range
Output destination & format options:
-o, --output-file=filename
Set output file-name (default: stdout)
-O, --output-format=format
Set output format
Supported output formats are: text/json
Output syntax:
text: [<glyph name or index>=<glyph cluster index within
input>@<horizontal displacement>,<vertical
displacement>+<horizontal advance>,<vertical advance>|...]
json: [{"g": <glyph name or index>, "ax": <horizontal
advance>, "ay": <vertical advance>, "dx": <horizontal
displacement>, "dy": <vertical displacement>, "cl": <glyph
cluster index within input>}, ...]
Output syntax options:
--show-text
Prefix each line of output with its corresponding input text
--show-unicode
Prefix each line of output with its corresponding input
codepoint(s)
--show-line-num
Prefix each line of output with its corresponding input line
number
-v, --verbose
Prefix each line of output with all of the above
--no-glyph-names
Output glyph indices instead of names
--no-positions
Do not output glyph positions
--no-advances
Do not output glyph advances
--no-clusters
Do not output cluster indices
--show-extents
Output glyph extents
--show-flags
Output glyph flags
--ned No Extra Data; Do not output clusters or advances
-V, --trace
Output interim shaping results
Application Options:
--version
Show version numbers
-n, --num-iterations=N
Run shaper N times (default: 1)
Shows results of shaping text with a given font in textual or JSON
format.
0: Success.
1: Option parsing failed.
2: Failed loading font face.
3: Operation failed.
4: Failed setting font functions.
HB_FACE_LOADER=face-loader; Overrides the default face loader.
HB_FONT_FUNCS=font-funcs; Overrides the default font-funcs.
HB_SHAPER_LIST=shaper-list; Overrides the default shaper list.
hb-view(1), hb-shape(1), hb-subset(1), hb-info(1)
Find more information or report bugs at
<https://github.com/harfbuzz/harfbuzz>
HarfBuzz 11.3.3 July 2025 HB-SHAPE(1)
NAME
hb-shape - manual page for hb-shape 11.3.3
DESCRIPTION
Usage:
hb-shape [OPTION?] [FONT-FILE] [TEXT]
Shape text with given font.
Help Options:
-h, --help
Show help options
--help-all
Show all help options
--help-face
Options for the font face
--help-font
Options for the font instance
--help-variations
Options for font variations used
--help-text
Options for the input text
--help-text-context
Options for the input context text
--help-shape
Options for the shaping process
--help-features
Options for font features used
--help-output
Options for the destination & form of the output
--help-output-syntax
Options for the syntax 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
Font-instance options:
--font-size=1/2 integers or 'upem'
Font size (default: upem)
--font-ppem=1/2 integers
Set x,y pixels per EM (default: 0; disabled)
--font-ptem=point-size
Set font point-size (default: 0; disabled)
--font-bold=1/2 numbers; eg. 0.05
Set synthetic bold (default: 0)
--font-grade=1/2 numbers; eg. 0.05
Set synthetic grade (default: 0)
--font-slant=slant ratio; eg. 0.2
Set synthetic slant (default: 0)
--font-funcs=impl
Set font functions implementation to use (default: ot)
Supported font function implementations are: ot/ft
--list-font-funcs
List available font functions and quit
--ft-load-flags=integer
Set FreeType load-flags (default: 2)
Variations options:
--named-instance=index
Set named-instance index (default: none)
--variations=list
Comma-separated list of font variations
Variations are set globally. The format for specifying
variation settings follows. All valid CSS
font-variation-settings values other than 'normal' and
'inherited' are also accepted, though, not documented below.
The format is a tag, optionally followed by an equals sign,
followed by a number. For example:
"wght=500" "slnt=-7.5"
Text options:
If no text is provided, standard input is used for input.
--text=string
Set input text
--text-file=filename
Set input text file-name
-u, --unicodes=list of hex numbers
Set input Unicode codepoints
--single-par
Treat text as single paragraph
Textual context options:
--text-before=string
Set text context before each line
--text-after=string
Set text context after each line
--unicodes-before=list of hex numbers
Set Unicode codepoints context before each line
--unicodes-after=list of hex numbers
Set Unicode codepoints context after each line
Shape options:
--shapers=comma-separated list
Set shapers to use (default: graphite2)
Supported shapers are: graphite2/ot/fallback
--list-shapers
List available shapers and quit
--direction=ltr/rtl/ttb/btt
Set text direction (default: auto)
--language=BCP 47 tag
Set text language (default: $LANG)
--script=ISO-15924 tag
Set text script (default: auto)
--bot Treat text as beginning-of-paragraph
--eot Treat text as end-of-paragraph
--preserve-default-ignorables
Preserve Default-Ignorable characters
--remove-default-ignorables
Remove Default-Ignorable characters
--invisible-glyph
Glyph value to replace Default-Ignorables with
--not-found-glyph
Glyph value to replace not-found characters with
--not-found-variation-selector-glyph
Glyph value to replace not-found variation-selector characters
with
--utf8-clusters
Use UTF8 byte indices, not char indices
--cluster-level=0/1/2/3
Cluster merging level (default: 0)
--normalize-glyphs
Rearrange glyph clusters in nominal order
--unsafe-to-concat
Produce unsafe-to-concat glyph flag
--safe-to-insert-tatweel
Produce safe-to-insert-tatweel glyph flag
--glyphs
Interpret input as glyph string
--verify
Perform sanity checks on shaping results
Features options:
--features=list
Comma-separated list of font features
Features can be enabled or disabled, either globally or
limited to specific character ranges. The format for
specifying feature settings follows. All valid CSS
font-feature-settings values other than 'normal' and the
global values are also accepted, though not documented below.
CSS string escapes are not supported. The range indices refer
to the positions between Unicode characters, unless the
--utf8-clusters is provided, in which case range indices refer
to UTF-8 byte indices. The position before the first character
is always 0.
The format is Python-esque.
Here is how it all works:
Syntax:
Value: Start: End:
Setting value:
"kern" 1 0 ? # Turn feature on
"+kern"
1 0 ? # Turn feature on
"-kern"
0 0 ? # Turn feature off
"kern=0"
0 0 ? # Turn feature off
"kern=1"
1 0 ? # Turn feature on
"aalt=2"
2 0 ? # Choose 2nd alternate
Setting index:
"kern[]"
1 0 ? # Turn feature on
"kern[:]"
1 0 ? # Turn feature on
"kern[5:]"
1 5 ? # Turn feature on, partial
"kern[:5]"
1 0 5 # Turn feature on, partial
"kern[3:5]"
1 3 5 # Turn feature on, range
"kern[3]"
1 3 3+1 # Turn feature on, single char
Mixing it all:
"aalt[3:5]=2" 2
3 5 # Turn 2nd alternate on for range
Output destination & format options:
-o, --output-file=filename
Set output file-name (default: stdout)
-O, --output-format=format
Set output format
Supported output formats are: text/json
Output syntax:
text: [<glyph name or index>=<glyph cluster index within
input>@<horizontal displacement>,<vertical
displacement>+<horizontal advance>,<vertical advance>|...]
json: [{"g": <glyph name or index>, "ax": <horizontal
advance>, "ay": <vertical advance>, "dx": <horizontal
displacement>, "dy": <vertical displacement>, "cl": <glyph
cluster index within input>}, ...]
Output syntax options:
--show-text
Prefix each line of output with its corresponding input text
--show-unicode
Prefix each line of output with its corresponding input
codepoint(s)
--show-line-num
Prefix each line of output with its corresponding input line
number
-v, --verbose
Prefix each line of output with all of the above
--no-glyph-names
Output glyph indices instead of names
--no-positions
Do not output glyph positions
--no-advances
Do not output glyph advances
--no-clusters
Do not output cluster indices
--show-extents
Output glyph extents
--show-flags
Output glyph flags
--ned No Extra Data; Do not output clusters or advances
-V, --trace
Output interim shaping results
Application Options:
--version
Show version numbers
-n, --num-iterations=N
Run shaper N times (default: 1)
Shows results of shaping text with a given font in textual or JSON
format.
EXIT CODES
0: Success.
1: Option parsing failed.
2: Failed loading font face.
3: Operation failed.
4: Failed setting font functions.
ENVIRONMENT
HB_FACE_LOADER=face-loader; Overrides the default face loader.
HB_FONT_FUNCS=font-funcs; Overrides the default font-funcs.
HB_SHAPER_LIST=shaper-list; Overrides the default shaper list.
SEE ALSO
hb-view(1), hb-shape(1), hb-subset(1), hb-info(1)
Find more information or report bugs at
<https://github.com/harfbuzz/harfbuzz>
HarfBuzz 11.3.3 July 2025 HB-SHAPE(1)