Skip to main content

​
Font Families

​
Basic Font Setup

# Set primary font
font-family = JetBrains Mono

# Set font size (in points)
font-size = 13
List available fonts: 
ghostty +list-fonts
On macOS, the default font size is 13pt. On other platforms, it’s 12pt.

​
Font Size Details

# Font size can be non-integer
font-size = 13.5  # On 2x display: 13.5pt × 2px/pt = 27px
Linux/GTK: Font size is scaled by display-wide and text-specific scaling factors (e.g., GNOME display scale and large text settings).
Reloading affects terminals that haven’t manually adjusted their font size (via increase/decrease font size actions). Terminals with manual adjustments retain their size.

​
Font Fallbacks

Specify multiple fonts for missing glyphs: 
# Primary font
font-family = JetBrains Mono

# Fallback fonts (for symbols, emoji, etc.)
font-family = Symbols Nerd Font
font-family = Noto Color Emoji
Fallback fonts are used in order when glyphs are missing from the primary font.

​
Emoji Fonts

Ghostty always uses Apple Color Emoji by default. Override by specifying an emoji font:
font-family = JetBrains Mono
font-family = MyEmojiFont

​
Resetting Font List

Clear previous fonts before setting new ones: 
# In config file
font-family = ""  # Clear previous fonts
font-family = Fira Code
CLI arguments automatically clear config file fonts, so you don’t need --font-family="" on the command line.

​
Font Styles

​
Style-Specific Fonts

Set different fonts for bold, italic, and bold-italic: 
font-family = JetBrains Mono
font-family-bold = JetBrains Mono Bold
font-family-italic = JetBrains Mono Italic
font-family-bold-italic = JetBrains Mono Bold Italic
Ghostty searches the regular font family for stylistic variants. If not found, it uses the regular style or synthesizes the style.
If you specify font-family-bold = FooBar but FooBar doesn’t exist, Ghostty falls back to the regular font-family for bold text.

​
Named Font Styles

Use specific font style names: 
font-style = Heavy           # Use "Heavy" style for regular
font-style-bold = Black      # Use "Black" style for bold
font-style-italic = Light Italic
Style names come from the font itself. For example, “Iosevka Heavy” has a style named “Heavy”.

​
Disabling Font Styles

Disable specific styles entirely: 
# Disable bold completely
font-style-bold = false

# When programs request bold, regular font is used instead
This only affects requested styles. If a font doesn’t have the style, you don’t need to disable it.

​
Synthetic Styles

Control synthetic (generated) font styles: 
# Enable all synthetic styles (default)
font-synthetic-style = true

# Disable all synthetic styles
font-synthetic-style = false

# Disable specific styles
font-synthetic-style = no-bold
font-synthetic-style = no-italic
font-synthetic-style = no-bold,no-italic
Important: Disabling bold or italic does NOT disable bold-italic. To disable bold-italic, explicitly set:
font-synthetic-style = no-bold-italic
Ghostty can synthesize styles if the font lacks them:
  • Bold: Draws an outline around glyphs
  • Italic: Applies a slant to glyphs
  • Bold-Italic: Both outline and slant
Synthetic styles don’t look as good as native styles, but they provide styled text when unavailable.

​
Font Features

Enable or disable OpenType font features: 
# Enable features
font-feature = liga  # Ligatures
font-feature = +calt # Contextual alternates
font-feature = ss01  # Stylistic set 01

# Disable features
font-feature = -calt # Disable ligatures
font-feature = -liga

# Set feature values
font-feature = cv01=2  # Character variant 01, value 2
To disable programming ligatures, use -calt (most common). To disable most ligatures: -calt, -liga, -dlig.

​
Feature Syntax

Multiple syntax forms are supported: 
font-feature = calt        # Enable
font-feature = +calt       # Enable
font-feature = calt on     # Enable
font-feature = calt=1      # Enable with value
font-feature = -calt       # Disable
font-feature = calt off    # Disable
font-feature = calt=0      # Disable
font-feature = "calt"      # Quoted (CSS-compatible)
Use a font inspection tool like fontdrop.info to explore available OpenType features.

​
Variable Fonts

Configure variable font axes: 
# Adjust weight axis
font-variation = wght=500

# Multiple axes
font-variation = wght=500
font-variation = slnt=-10

# Style-specific variations
font-variation-bold = wght=700
font-variation-italic = slnt=-12
font-variation-bold-italic = wght=700
font-variation-bold-italic = slnt=-12
Variable fonts usually have filenames ending in -VF.ttf or -VF.otf.

​
Common Variable Font Axes

AxisDescriptionExample
wghtWeightwght=400 (regular) to wght=700 (bold)
slntSlantslnt=-10 (italic slant)
italItalicital=1 (italic on)
opszOptical sizeopsz=12 (for 12pt display)
wdthWidthwdth=100 (normal) to wdth=125 (wide)
GRADGradientFont-specific
Invalid axis IDs or out-of-range values are usually ignored. Check your font’s documentation for supported ranges.

​
Font Rendering

​
FreeType Options (Linux)

Configure FreeType font rendering: 
# Enable/disable features
freetype-load-flags = hinting           # Enable hinting (default)
freetype-load-flags = no-hinting        # Disable hinting
freetype-load-flags = force-autohint    # Always use auto-hinter
freetype-load-flags = light             # Light hinting (default)
freetype-load-flags = monochrome        # 1-bit rendering (no anti-aliasing)
FreeType flags only affect Linux builds using FreeType for rendering.

​
Font Thickening (macOS)

# Enable font thickening
font-thicken = true

# Thicken strength (0-255)
font-thicken-strength = 255  # Maximum
font-thicken-strength = 128  # Medium
font-thicken-strength = 0    # Lightest
Font thickening is currently only supported on macOS.

​
Font Metrics Adjustments

Fine-tune font rendering metrics: 
# Adjust cell dimensions
adjust-cell-width = 1      # Add 1 pixel
adjust-cell-width = 10%    # Add 10%
adjust-cell-height = -5%   # Reduce by 5%

# Adjust font baseline
adjust-font-baseline = 2   # Move baseline up 2px

# Adjust underline
adjust-underline-position = 1    # Move underline down
adjust-underline-thickness = 1   # Thicker underline

# Adjust cursor
adjust-cursor-thickness = 2      # Thicker cursor
adjust-cursor-height = 10%       # Taller cursor
Values can be integers (1, -1) or percentages (20%, -15%). They modify the original value, not replace it.Wrong values (e.g., -100%) can make the terminal unusable.

​
Available Adjustments

  • adjust-cell-width: Horizontal cell size
  • adjust-cell-height: Vertical cell size (font is centered)
Note: Powerline glyphs adjust with cell height to maintain alignment.
  • adjust-underline-position: Distance from top to underline
  • adjust-underline-thickness: Underline thickness
  • adjust-strikethrough-position: Distance from top to strikethrough
  • adjust-strikethrough-thickness: Strikethrough thickness
  • adjust-overline-position: Distance from top to overline
  • adjust-overline-thickness: Overline thickness
  • adjust-font-baseline: Distance from bottom to baseline (increase = move up)
  • adjust-cursor-thickness: Bar and outlined rect cursor thickness
  • adjust-cursor-height: Cursor height (all types)
  • adjust-box-thickness: Box drawing character thickness
  • adjust-icon-height: Maximum height for Nerd Font icons (since 1.2.0)

​
Codepoint Mapping

Force specific Unicode ranges to use specific fonts: 
# Map a single codepoint
font-codepoint-map = U+1F47B=Apple Color Emoji

# Map a range
font-codepoint-map = U+2500-U+257F=Symbols Nerd Font

# Map multiple ranges
font-codepoint-map = U+2500-U+257F,U+E0A0-U+E0A3=Symbols Nerd Font
Changing codepoint mapping at runtime only affects new terminals (new windows, tabs, etc.).
Useful for:
  • Special symbols that render better in specific fonts
  • Box drawing characters
  • Powerline symbols
  • Icon fonts (Nerd Fonts)
  • Emoji control

​
Font Shaping

Control when font shaping runs are broken: 
# Break shaping under the cursor (shows individual characters)
font-shaping-break = cursor

# Don't break shaping anywhere (keeps all ligatures)
font-shaping-break = no-cursor
A “run” is contiguous text shaped together to form ligatures and other features. Breaking runs prevents ligatures from forming.Breaking under the cursor helps see individual characters during text editing.
Font shaping break is available since version 1.2.0.

​
Grapheme Width

Control how grapheme cluster width is calculated: 
grapheme-width-method = unicode  # Unicode standard (default)
grapheme-width-method = legacy   # Legacy wcswidth-like method
  • unicode: Correct width for emoji, non-English characters, etc. Some legacy programs may have cursor-desync issues.
  • legacy: Maximum compatibility with old programs. May display some graphemes incorrectly.
If a program enables terminal mode 2027, unicode width is forced automatically.
This only affects new terminals. Existing terminals keep their current method after config reload.

​
Font Examples

​
Minimal Setup

font-family = JetBrains Mono
font-size = 13

​
With Ligatures Disabled

font-family = Fira Code
font-feature = -calt
font-feature = -liga

​
Variable Font Setup

font-family = Recursive
font-variation = MONO=1
font-variation = CASL=0
font-variation-bold = wght=800

​
Multi-Font Setup

font-family = JetBrains Mono
font-family = Symbols Nerd Font Mono
font-family = Noto Color Emoji
font-size = 13

​
Resources

List Fonts

Run ghostty +list-fonts to see available fonts

Font Drop

Inspect OpenType features in your fonts

Nerd Fonts

Icon fonts for terminals

Google Fonts

Free font repository