kitten-choose-fonts(1)

📦
version 0.49.2 · 10 versions
, in arch rolling, nixpkgs unstable

🎀 NAME 🎀

kitten-choose-fonts — the kitten docs, bestie. Like, the actual documentation page for this icon of a kitten. 💅

So this is from the kitty manual set, and we're about to get into it. ✨

🌸 OVERVIEW 🌸

Okay so, terminal girlies spend literally all day staring at text — so getting text rendering exactly right? Not optional, it's a whole lifestyle. 🫶 And kitty has extremely powerful facilities for fine-tuning text rendering. She's not playing around.

Here's the tea on what she supports:

You can also:

  • select which font is used to render particular unicode codepoints — #opt-kitty.symbol_map 💖
  • modify font metrics — #opt-kitty.modify_font 🦋
  • and even adjust the gamma curves — #opt-kitty.text_composition_strategy — used for rendering text onto the background color 🌈

✨ the first step (aka the main character move) ✨

The first step is to select the font faces kitty will use for rendering regular, bold, and italic text. And good news: kitty comes with a convenient UI for choosing fonts, in the form of the choose-fonts kitten. Simply run:

kitten choose-fonts

and follow the on screen prompts. That's it. That's the whole vibe. 💅

🦋 how the screens go 🦋

First, choose the family you want — and the list of families can be easily filtered by typing a few letters from the family name you're looking for. The family selection screen shows you a preview of how the family looks. Preview supremacy, honestly. 💖

Once you select a family by pressing the Enter key, you're shown previews of what the regular, bold, and italic faces look like for that family.

You can choose to fine tune any of the faces. Start with fine-tuning the regular face by pressing the R key — and the other styles will be automatically adjusted based on what you select for the regular face. No cap, they just follow your lead. 👑

🎀 clicking around 🎀

You can choose a specific style or font feature by clicking on it. A precise value for any variable axes can be selected using the slider — in the screenshot above, the font supports precise weight adjustment. Slider moment. 🎚️✨

And if you are lucky, the font designer has included descriptive names for font features, which will be displayed. If not… consult the documentation of the font to see what each feature does. iykyk. 😭

💜 THE FONT SPECIFICATION SYNTAX 💜

If you don't like the choose fonts kitten — or simply want to understand and write font selection options into kitty.conf yourself — read on, bestie. 📖

There are four font face selection keys:

  • font_family
  • bold_font
  • italic_font
  • bold_italic_font

Each of these supports the syntax described below. Their values can be of three types:

  1. a font family name
  2. the keyword auto
  3. an extended key=value syntax for specifying font selection precisely

🌟 the three types, unpacked 🌟

If a font family name is specified, kitty will use Operating System APIs to search for a matching font.

The keyword auto means kitty will choose a font completely automatically — typically this is used for automatically selecting bold/italic variants once the font_family — #opt-kitty.font_family — is set. The bold and italic variants will then automatically use the same set of features as the main face. Teamwork, fr fr. 🫶

🧚 the key=value syntax 🧚

To specify font face selection more precisely, a key=value syntax is used. First, let's look at a few examples:

# Select by family only, actual face selection is automatic
font_family family="Fira Code"
# Select an exact face by Postscript name
font_family postscript_name=FiraCode
# Select an exact face by family with features and variable weight
font_family family=SourceCodeVF variable_name=SourceCodeUpright features="+zero cv01=2" wght=380

The following are the known keys — any other keys are names of variable axes, that is, they are used to set the variable value for some font characteristic. 👀

  • family — A font family name. A family typically has multiple actual font faces, such as bold and italic variants. One or more of the faces can even be variable, allowing fine tuning of font characteristics. 💖
  • style — A style name to choose a particular font from a given family. Useful only with the family key, when no more precise methods for face selection are specified. Can also be used to specify a named variable style for variable fonts. ✨
  • postscript_name — The actual postscript name for a font face. This allows selecting a particular variant within a font family. But note that postscript names are usually insufficient for selecting variable fonts. 💀
  • full_name — This can be used to select a particular font face in a family. However, it is less precise than postscript_name and should not generally be used. 🙈
  • variable_name — Some families with variable fonts actually contain multiple font files. For example, a family could have variable weights with one font file containing upright variable weight faces and another containing italic variable weight faces. Well designed fonts use a variable name to distinguish between such files. Should be used in conjunction with family to select a particular variable font file. 🦋
  • features — A space separated list of OpenType font features to enable/disable or select a value of, for this font. Consult the documentation for the font family to see what features it supports and their effects. The exact syntax for specifying features is documented by HarfBuzz — https://harfbuzz.github.io/harfbuzz-hb-common.html#hb-feature-from-string 🎀
  • system — This can be used to pass an arbitrary string, usually a family or full name, to the OS font selection APIs. Should not be used in conjunction with any other keys. Is the same as specifying just the font name without any keys. ⭐
💀 heads up: system does not play nice with other keys — don't mix them, bestie.

🔥 the variable axis bit 🔥

In addition to these keys, any four letter key is treated as the name of a variable characteristic of the font. Its value is used to set the value for the name. That's the whole rule — four letters, you're a variable axis now. periodt. 💅

👑 AUTHOR 👑

Kovid Goyal

2026, Kovid Goyal

and that's the whole page, bestie 💖✨ — this was kitten-choose-fonts(1) from the kitty docs, version 0.49.2, dated Oct 01, 2026. Go make your terminal gorgeous, you absolute icon. 🎀🦋💜

📦 where this page comes from