Fonts

Wintty's font pipeline is designed to feel native on every platform and to give you fine control when you want it. By default Wintty picks a sensible monospace font for your OS. By configuration, you can:

• Pick separate fonts for regular, bold, italic, and bold-italic styles.
• Enable or disable ligatures and other OpenType features.
• Control variable font axes (weight, slant, width).
• Remap specific Unicode ranges to a different font for better symbol coverage.
• Adjust per-metric tweaks (cell width, baseline, underline thickness).

font-family is repeatable. The first entry is the primary font; subsequent entries are fallbacks in order:

font-family = JetBrainsMono Nerd Font
font-family = Noto Sans Mono
font-family = Symbols Nerd Font

When Wintty needs to render a codepoint, it walks the list until it finds a font that has a glyph for it. This is how you get good emoji, symbol, and CJK coverage even when your primary coding font has narrow Unicode coverage.

You can specify separate fonts per style:

font-family            = MyMonoRegular
font-family-bold       = MyMonoBold
font-family-italic     = MyMonoItalic
font-family-bold-italic = MyMonoBoldItalic

If a style-specific family is not configured, Wintty uses the same font-family and asks the OS for the corresponding style. If the OS can't satisfy the request (the font has no italic, for example), see Synthetic Styles below.

To clear a previously set list and start over (useful when an imported config file already set families), assign an empty string before adding new entries:

font-family =
font-family = NewFont

font-size is in points and accepts non-integer values. The actual pixel size is the nearest available pixel size for the rendered face.

font-size = 13.5

Defaults to 12, biased to look good on typical display density.

Runtime resizing actions:

Action	Behavior
increase_font_size	Grow by a point amount
decrease_font_size	Shrink by a point amount
reset_font_size	Restore the configured size
set_font_size	Set an absolute size

Reloading the config updates the size only for surfaces that have not manually adjusted their size. Manually-adjusted surfaces keep their adjusted size until you reset them.

font-feature controls OpenType features. The syntax matches the CSS font-feature-settings property:

Form	Result
feat, +feat, feat on, feat=1	Enable the feature
-feat, feat off, feat=0	Disable the feature
feat=2, feat 4	Set a feature index

# Disable programming ligatures
font-feature = -calt

# Disable most common ligatures
font-feature = -calt, -liga, -dlig

# Enable a stylistic set
font-feature = ss01

-calt is the typical way to turn off programming ligatures (the !=, =>, -> style). Different fonts ship different sets of features; use a font inspector like fontdrop.info to see what's available in your font.

Note

Font features apply globally to every face Wintty renders. A future enhancement will allow per-face feature control.

If your font is a variable font (-VF.ttf, -VF.otf), you can set its axes with font-variation. Each value is a four-character axis tag and a numeric value:

font-variation = wght=420
font-variation = wdth=110

Common axes:

Tag	Meaning
wght	Weight (often 100..900)
slnt	Slant in degrees
ital	Italic axis (0..1)
opsz	Optical size
wdth	Width
GRAD	Grade (apparent weight without changing width)

You can target axes for each style independently:

font-variation              = wght=420
font-variation-bold         = wght=700
font-variation-italic       = wght=420, slnt=-10
font-variation-bold-italic  = wght=700, slnt=-10

Invalid axis ids or out-of-range values are silently ignored. Consult your font's documentation for the supported axes and ranges.

font-codepoint-map forces specific Unicode codepoints (or ranges) to render with a named font, overriding the normal fallback order. This is the right tool for "use this Nerd Font for symbols but keep my regular font for text":

font-codepoint-map = U+E000-U+F8FF=Symbols Nerd Font
font-codepoint-map = U+1F300-U+1F6FF=Apple Color Emoji

Syntax:

• Single codepoint: U+ABCD=fontname
• Range: U+ABCD-U+DEFG=fontname
• Multiple ranges, same font: U+ABCD-U+DEFG,U+1234-U+5678=fontname

The font name is what you'd use for font-family. Mappings only affect new terminals; existing surfaces keep their original mapping until you open a new one.

A related setting, clipboard-codepoint-map, replaces codepoints when copying to the clipboard. This is useful when your terminal uses Powerline or box-drawing characters but you want to paste ASCII into other apps:

clipboard-codepoint-map = U+2500=U+002D
clipboard-codepoint-map = U+2502=U+007C
clipboard-codepoint-map = U+03A3=SUM

Single codepoint replacements, ranges, and literal-string replacements are all supported.

font-style and its style-specific siblings select a named style from within the font (for example, "Heavy" inside Iosevka):

font-family = Iosevka
font-style  = Light
font-style-bold = Heavy

Setting any of these to literal false disables the corresponding style entirely. If a program asks for italic but italic is disabled, Wintty falls back to the regular style instead of synthesizing one.

When a requested style is not available in the chosen font, font-synthetic-style controls whether Wintty synthesizes one (by adding an outline for bold or applying a slant for italic):

# Default: synthesize anything missing
font-synthetic-style = true

# Disable all synthesis (fall back to regular instead)
font-synthetic-style = false

# Disable specific styles
font-synthetic-style = no-bold, no-italic

Warning

no-bold and no-italic do not disable bold-italic synthesis. If you want to disable the bold-italic combination, list it explicitly: font-synthetic-style = no-bold-italic or no-bold, no-italic, no-bold-italic.

Synthetic styles never look as good as a font that ships the style natively. They're a "looks fine when nothing else is available" fallback, not a substitute.

font-shaping-break tells Wintty where to split a text run for shaping. By default the cursor breaks runs so editing a character mid-ligature shows you the individual characters instead of the ligature:

font-shaping-break = cursor

Prefix with no- to disable a break:

font-shaping-break = no-cursor

You can combine values with commas; this is forward-compatible as more break points are added.

If you need to nudge the rendered font metrics (because the font has unusual line height, the baseline is off, or you want a thicker underline), Wintty exposes a set of adjust-* options:

Option	Purpose
adjust-cell-width	Change the cell width
adjust-cell-height	Change the cell height (font centers vertically)
adjust-font-baseline	Move the text baseline up/down
adjust-underline-position	Move the underline up/down
adjust-underline-thickness	Change the underline thickness
adjust-strikethrough-position	Move the strikethrough up/down
adjust-strikethrough-thickness	Change the strikethrough thickness
adjust-overline-position	Move the overline up/down
adjust-overline-thickness	Change the overline thickness
adjust-cursor-thickness	Change the cursor bar/outline thickness
adjust-cursor-height	Change the cursor height
adjust-box-thickness	Change the thickness of box-drawing characters
adjust-icon-height	Change the maximum height for Nerd Font icons

Each value is a relative adjustment, not an absolute setting. Numbers add a fixed amount; percentages scale by a percentage:

# Add 2 pixels to cell height
adjust-cell-height = 2

# Increase cell width by 5 percent
adjust-cell-width = 5%

# Make the underline 2 pixels thicker
adjust-underline-thickness = 2

# Move the baseline 1 pixel up
adjust-font-baseline = 1

Warning

These options have very little validation. Setting adjust-cell-width = -100% will collapse your cells to nothing. Use sensible values and reload after each change so you can revert.

alpha-blending controls the color space used when blending glyphs against the background. This affects how text edges look:

Value	Behavior
native	Blend in the OS's native space (sRGB on Windows).
linear	Blend in linear space. Removes darkening artifacts on contrasting colors (red on green), but makes dark text look thin and light text look thick.
linear-corrected	Same as linear, with a correction that keeps text looking nearly identical to native. The default.

If your text looks too thin on dark backgrounds, try alpha-blending = native. If you see strong color darkening on green-on-red or red-on-green, try one of the linear modes.

To see which fonts Wintty can find on your system:

wintty +list-fonts

The output is grouped by family. Each family name is printed on its own line, followed by the full name of every font in that family, indented underneath it. The family name is the value you use for font-family.

Option	Purpose
font-family	Primary font family; repeatable for fallbacks
font-family-bold	Bold font family
font-family-italic	Italic font family
font-family-bold-italic	Bold-italic font family

Option	Purpose
font-size	Font size in points
font-style	Named style override for the regular face
font-style-bold	Named style override for bold
font-style-italic	Named style override for italic
font-style-bold-italic	Named style override for bold-italic
font-synthetic-style	Synthesize missing styles or fall back to regular

Option	Purpose
font-feature	OpenType feature settings (ligatures, stylistic sets)
font-variation	Variable font axes for the regular face
font-variation-bold	Variable axes for bold
font-variation-italic	Variable axes for italic
font-variation-bold-italic	Variable axes for bold-italic
font-shaping-break	Where to break shaping runs

Option	Purpose
font-codepoint-map	Force codepoints/ranges to a specific font
clipboard-codepoint-map	Replace codepoints on copy-to-clipboard

Option	Purpose
alpha-blending	Color space used for alpha blending

See the Metric Adjustments section above for the full list of adjust-* options.

Action	Purpose
increase_font_size	Grow font size by a point amount
decrease_font_size	Shrink font size by a point amount
set_font_size	Set an absolute font size
reset_font_size	Restore the configured font size