Configure Kitty: fonts, colours, transparency and terminal images

A terminal should be comfortable to read, dependable every day and a good fit for your desktop. Kitty combines a local text configuration with GPU rendering and an image protocol. A small configuration file is enough to choose fonts, background colours and scrollback deliberately.

This guide starts with my real Kitty configuration in the Gruvnode X1 profile. We use a separate test file first. You need Kitty installed and a graphical Linux session; keep your usual terminal open throughout the exercise.

Understand the terminal and the shell

Kitty is the window that displays text and passes keyboard input to programs. fish or Bash interpret the commands inside it. Changing a Kitty font therefore does not change your login shell or the syntax of your scripts. XMonad and Sway have separate responsibilities too: managing windows or running the Wayland session.

This distinction makes troubleshooting easier. Missing characters suggest a font problem. A syntax error suggests a shell problem. Transparency under X11 also depends on a compositor. My Gruvnode guide explains how these parts fit together on the X1 Carbon.

Check the installed version:

kitty --version

Read my small configuration

This excerpt comes from the X1 profile:

font_family JetBrains Mono
font_size 11.0
background #1d2021
foreground #ebdbb2
background_opacity 0.8
dynamic_background_opacity no
scrollback_lines 10000
enable_audio_bell no

Each line contains an option and its value. There are no braces or semicolons. Comments start with # on their own line; the # within a colour value has a different purpose.

The original also defines cursor and selection colours. It does not specify an entire ANSI palette. Programs that set their own colours can consequently look different from the default text.

Create a separate test file

Create an exercise directory. Choose another name if this one already contains your work:

mkdir -p ~/kitty-tutorial

Use your editor to save the following complete file as ~/kitty-tutorial/kitty.conf. Begin with an opaque background:

font_family monospace
font_size 12.0
background #1d2021
foreground #ebdbb2
cursor #ebdbb2
background_opacity 1.0
scrollback_lines 5000
enable_audio_bell no

Launch a dedicated window with that file:

kitty --config ~/kitty-tutorial/kitty.conf

Expect a dark background, light text and a new shell. This command does not replace ~/.config/kitty/kitty.conf. Close the test window to return to your usual setup.

Choose a font and check icon support

Change only font_size, for example from 12.0 to 13.0, and reopen the test window. Ctrl + Shift + F5 can reload a running configuration. Reopening the test window is a straightforward beginner workflow because some settings take effect only at startup.

To request JetBrains Mono, install that font first. List the font families Kitty can find:

kitty +list-fonts

Use the actual reported family name. JetBrains Mono and the icon-enhanced JetBrainsMono Nerd Font have different names. My Fastfetch configuration needs fonts containing its extra symbols. Boxes in place of icons are a reason to investigate fonts first; a text-only logo makes a useful baseline.

Transparency depends on your desktop

Set background_opacity 0.8 in the test file and open a new window. The value means 80 percent opacity. Keep text contrast comfortable: heavy transparency over a busy wallpaper can make reading tiring.

X11 needs a compositor for this effect; my Gruvnode desktop uses Picom. On Wayland, the session compositor, such as KWin or Sway, handles display composition. Starting Picom inside a Wayland session is not a suitable fix.

My profile sets dynamic_background_opacity no, so Kitty's dynamic opacity controls are not enabled. For this exercise, edit the file and reopen the window. An editor that paints its own opaque cell backgrounds may also leave parts of the terminal opaque.

Display a local image

Run the following command inside the test Kitty window. Replace the example path with an existing local image. The quotes protect spaces:

kitten icat "$HOME/Pictures/my-logo.png"

The image appears inside the terminal; this is separate from a desktop wallpaper. Clear the displayed image with:

kitten icat --clear

If it does not appear, check the filename, read permissions and terminal support. SSH sessions, multiplexers and other terminals introduce additional conditions. Begin directly in a local Kitty window. The Fastfetch guide builds on this distinction between the image file, the rendering mechanism and the configuration.

Apply selected changes and understand data flows

When you like the test settings, back up any existing regular file before editing it. Transfer only the desired lines with your editor. Kitty usually reads ~/.config/kitty/kitty.conf; a different XDG_CONFIG_HOME or KITTY_CONFIG_DIRECTORY can change the location.

These settings use local files. A terminal can still run network commands whenever you launch them. Official Kitty binary builds can also check for updates; distribution packages and source builds differ according to the documentation. A local configuration gives you a controllable component, rather than a guarantee about every program run within it.

Configuration and references

• My X1 Kitty profile on GitHub: the checked starting revision.
• Kitty configuration reference: options, file locations and reloading.
• Kitty icat: image display and requirements.
• Kitty fonts: choosing fonts and family names.

Configuration and references checked on 8 October 2026. The exercise targets local Linux desktops; it does not replace testing on your graphics hardware.