ghostty berkeley mono font configuration

published: August 30, 2025 •
ghosttyfontsberkeley-monofontconfigterminaltypography
on this page

tl;dr

Config:

curl -o ~/.config/ghostty/config https://michaelbommarito.com/wiki/ghostty-berkeley-mono.config

Font Family:Berkeley Mono Variable with customizable weight and width axes
Key Discovery:Use font family names, not style descriptors
Debug Tool:fc-match "Font Name" -v | grep family
Features:Ligatures, contextual alternates, slashed zero

i used the berkeley mono font compiler to build my own custom variable OTF, but struggled to get ghostty to pick it up correctly at first. here’s what i did wrong and the fix.

overview

berkeley mono is “that” font - the one that even rabid free software folks still shell out money for. depending on what you pay for, you might also get access to the variable font compiler, which allows you to generate a custom font package to your specs. if you do this, you’ll need to be careful when you set up your config in ghostty.

the easiest thing to do is to download mine and edit to match yuor font name. you can download my complete berkeley mono ghostty config or follow the detailed setup below.

the font resolution problem

ghostty uses fontconfig for font resolution, creating a two-layer system that can be confusing:

  1. ghostty’s font listing - shows all available font variants for user reference
  2. fontconfig’s database - actually resolves font names to font files

the critical issue: fontconfig treats font families and styles differently than how they appear in font listings.

what went wrong initially

# this fails - fontconfig can't find this "family"
font-family = Berkeley Mono SemiCondensed

# fontconfig interprets this as looking for a font family named
# "Berkeley Mono SemiCondensed" which doesn't exist

the solution

# this works - uses the actual font family name
font-family = Berkeley Mono

# fontconfig finds the "Berkeley Mono" family and automatically
# selects the default style (SemiCondensed in this case)

understanding font systems

ghostty’s font listing

ghostty shows descriptive names for disambiguation:

$ ghostty +list-fonts | grep "Berkeley Mono" | head -5
Berkeley Mono
    Berkeley Mono Black SemiCondensed
    Berkeley Mono Black SemiCondensed Oblique
    Berkeley Mono Bold SemiCondensed
    Berkeley Mono Bold SemiCondensed Oblique

these are display names to help you identify variants, not the actual font family names.

fontconfig’s perspective

fontconfig only recognizes actual font families:

$ fc-list | grep "Berkeley Mono" | cut -d: -f2 | cut -d, -f1 | sort -u
 Berkeley Mono
 Berkeley Mono Variable ZY761Y88

key insight: only two font families exist - everything else is a style variant within those families.

debugging font resolution

1. testing fontconfig resolution

verify how fontconfig resolves font names:

# test with family name only (works)
$ fc-match "Berkeley Mono" -v | grep -E "(family|style|file)" | head -6
family: "Berkeley Mono"(s) "TX-02 SemiCondensed"(s)
familylang: "en"(s) "en"(w)
style: "SemiCondensed"(s) "Regular"(s)
stylelang: "en"(s) "en"(w)
file: "/home/user/.local/share/fonts/Berkeley_Mono_SemiCondensed.otf"(s)
# ✅ successfully resolves to berkeley mono, auto-selecting semicondensed style
# test with family + style as one string (fails)
$ fc-match "Berkeley Mono SemiCondensed" -v | grep -E "(family|style|file)" | head -6
family: "Noto Sans"(w)
familylang: "en"(s)
style: "Regular"(s)
stylelang: "en"(s)
file: "/usr/share/fonts/truetype/noto/NotoSans-Regular.ttf"(s)
# ❌ falls back to noto sans - fontconfig can't find this "family"

2. listing font properties

examine detailed font properties:

$ fc-list -v "Berkeley Mono Variable ZY761Y88" | grep -E "(family|style|weight|width)" | head -10
family: "Berkeley Mono Variable ZY761Y88"(s)
familylang: "en"(s)
style: "Regular"(s)
stylelang: "en"(s)
weight: [0 215](r)
width: [50 125](r)
# shows variable font axes ranges: weight 0-215, width 50-125

3. finding font file locations

locate actual font files:

$ fc-list "Berkeley Mono" | head -3
/home/user/.local/share/fonts/Berkeley_Mono_Bold_SemiCondensed_Oblique.otf: Berkeley Mono:style=Bold SemiCondensed Oblique
/home/user/.local/share/fonts/Berkeley_Mono_Bold_SemiCondensed.otf: Berkeley Mono:style=Bold SemiCondensed
/home/user/.local/share/fonts/Berkeley_Mono_SemiCondensed.otf: Berkeley Mono,TX-02 SemiCondensed:style=SemiCondensed,Regular

4. checking font fallback chain

see what fonts will be used as fallbacks:

$ fc-match -s "Berkeley Mono" | head -5
Berkeley Mono SemiCondensed.otf: "Berkeley Mono" "SemiCondensed"
Berkeley Mono Bold SemiCondensed.otf: "Berkeley Mono" "Bold SemiCondensed"
NotoSans-Regular.ttf: "Noto Sans" "Regular"
DejaVuSans.ttf: "DejaVu Sans" "Book"

variable fonts explained

variable fonts contain multiple styles in a single file with adjustable axes.

checking variable font capabilities

$ fc-query "/path/to/Berkeley_Mono_Variable.otf" | grep -E "(variable|axes)"
variable: True(s)

common variable font axes

  • wght (weight): 100=thin, 400=regular, 700=bold, 900=black
  • wdth (width): 50=ultracondensed, 75=condensed, 87.5=semicondensed, 100=normal, 125=extended
  • slnt (slant): angle of italic/oblique
  • ital (italic): 0=roman, 1=italic

berkeley mono variable axes

berkeley mono variable supports:

  • weight: 0-215 (mapped to standard 100-900 scale)
  • width: 50-125 (condensed to extended)

optimal configurations

basic setup (static fonts)

simple configuration using static font files:

# ~/.config/ghostty/config
font-family = Berkeley Mono
font-size = 11

# fontconfig automatically selects bold/italic variants
# when the terminal needs them

advanced setup (variable font)

leverage the variable font for fine-tuned control:

# use the variable font family
font-family = Berkeley Mono Variable ZY761Y88

# fine-tune appearance with variable axes
font-variation = wght=450  # slightly bolder than regular (400)
font-variation = wdth=87.5  # semicondensed width

# enable opentype features
font-feature = +liga  # standard ligatures (-> becomes →, != becomes ≠)
font-feature = +calt  # contextual alternates (adjusts glyphs based on context)
font-feature = +ss01  # stylistic set 1 (alternate glyph designs)
font-feature = +ss02  # stylistic set 2 (more alternates)
font-feature = +zero  # slashed zero (0 vs o distinction)

weight and width values

experiment with these variable axis values:

# weight examples
font-variation = wght=300  # light
font-variation = wght=400  # regular
font-variation = wght=500  # medium
font-variation = wght=600  # semibold
font-variation = wght=700  # bold

# width examples
font-variation = wdth=75   # condensed
font-variation = wdth=87.5 # semicondensed
font-variation = wdth=100  # normal
font-variation = wdth=110  # slightly extended

opentype features

discovering available features

list opentype features in a font (requires otfinfo from lcdf-typetools):

$ otfinfo -f /path/to/Berkeley_Mono.otf
liga    Standard Ligatures
calt    Contextual Alternates
ss01    Stylistic Set 1
ss02    Stylistic Set 2
zero    Slashed Zero
onum    Oldstyle Figures
tnum    Tabular Figures

common programming font features

  • liga/clig: combine character sequences (e.g., => to ⇒)
  • calt: smart character substitution based on context
  • ss01-ss20: alternative character designs (varies by font)
  • zero: disambiguate zero from letter o
  • cv01-cv99: character variants for specific glyphs

troubleshooting workflow

1. verify font installation

$ fc-list | grep -i "berkeley"
# should show your berkeley mono font files

2. check ghostty’s view

$ ghostty +list-fonts | grep -i "berkeley"
# shows all variants ghostty can see

3. test fontconfig resolution

$ fc-match "Berkeley Mono" -v | grep family
# shows what font actually gets selected

4. verify ghostty configuration

$ ghostty +show-config | grep "^font-"
# shows active font settings

5. debug fallback fonts

$ fc-match -s "Berkeley Mono" | head -5
# shows fallback chain if primary font fails

why simple names work

when you specify font-family = Berkeley Mono:

  1. fontconfig searches for a font family named “Berkeley Mono” ✅
  2. finds the family and sees multiple styles available
  3. auto-selects the default style (semicondensed in this case)
  4. can still find bold/italic variants within the same family

when you specify font-family = Berkeley Mono SemiCondensed:

  1. fontconfig searches for a font family named “Berkeley Mono SemiCondensed” ❌
  2. no such family exists (semicondensed is a style, not part of the family name)
  3. falls back to default system font (noto sans)

platform-specific notes

linux font management

  • font directories:
    • user: ~/.local/share/fonts/
    • system: /usr/share/fonts/
  • cache refresh: run fc-cache -fv after installing new fonts
  • gtk applications: may have additional font rendering settings via gsettings

font installation

# install berkeley mono fonts
mkdir -p ~/.local/share/fonts
cp /path/to/berkeley-mono-fonts/*.otf ~/.local/share/fonts/

# rebuild font cache
fc-cache -fv

# verify installation
fc-list | grep -i berkeley

quick reference

essential commands

# list all fonts
ghostty +list-fonts

# test font resolution
fc-match "Font Name" -v

# show ghostty config
ghostty +show-config

# reload config
# press ctrl+shift+, in ghostty

configuration hierarchy

  1. exact family name works best
  2. fontconfig auto-selects styles
  3. variable fonts offer most control
  4. fallback fonts provide safety net

related pages

more in programming

on this page