Zellij config

References

Config file

Zellij uses KDL for configuration. On Linux, the usual config file is:

~/.config/zellij/config.kdl

Create it from the default config:

mkdir -p ~/.config/zellij
test -f ~/.config/zellij/config.kdl || zellij setup --dump-config > ~/.config/zellij/config.kdl

Zellij searches for configuration in this order:

--config-dir
ZELLIJ_CONFIG_DIR
$HOME/.config/zellij
platform default config directory
/etc/zellij

Use a specific file when testing a config change:

zellij --config ~/.config/zellij/config.kdl

Start without loading user configuration:

zellij options --clean

Zellij watches the active config file. Most config changes are applied to running sessions without restarting Zellij.

Root options

Set common options at the root of config.kdl:

~/.config/zellij/config.kdl
theme "tokyo-night"
default_shell "zsh"
default_layout "default"
default_mode "normal"
pane_frames true
mouse_mode true
scroll_buffer_size 10000
copy_on_select true
show_startup_tips false

Useful root options include:

theme: color theme name.
default_shell: shell used for new panes.
default_layout: layout loaded on startup.
default_mode: mode used when Zellij starts.
pane_frames: show or hide pane borders.
mouse_mode: enable mouse selection and pane interaction.
scroll_buffer_size: scrollback lines kept for each pane.
copy_on_select: copy selected text automatically.

Theme

Use a built-in theme by setting theme:

~/.config/zellij/config.kdl
theme "nord"

Common built-in themes include:

dracula
gruvbox-dark
kanagawa
nord
tokyo-night
tokyo-night-storm
catppuccin-frappe
catppuccin-macchiato
catppuccin-latte

Override the theme only for one startup:

zellij options --theme nord

Custom theme

Put custom theme files under the active config directory:

~/.config/zellij/themes/<theme-name>.kdl

Then load the theme by name:

~/.config/zellij/config.kdl
theme "my-theme"

Set a custom theme directory if themes live elsewhere:

~/.config/zellij/config.kdl
theme_dir "~/.config/zellij/themes"
theme "my-theme"

For quick palette-style themes, Zellij still supports the legacy theme format:

~/.config/zellij/themes/my-theme.kdl
themes {
    my-theme {
        fg "#D8DEE9"
        bg "#2E3440"
        black "#3B4252"
        red "#BF616A"
        green "#A3BE8C"
        yellow "#EBCB8B"
        blue "#81A1C1"
        magenta "#B48EAD"
        cyan "#88C0D0"
        white "#E5E9F0"
        orange "#D08770"
    }
}

For new full themes, prefer the current UI-component theme specification from the Zellij theme documentation.

Keybindings

Configure keybindings in the keybinds block:

~/.config/zellij/config.kdl
keybinds {
    normal {
        bind "Alt h" { MoveFocus "Left"; }
        bind "Alt j" { MoveFocus "Down"; }
        bind "Alt k" { MoveFocus "Up"; }
        bind "Alt l" { MoveFocus "Right"; }
        bind "Alt n" { NewPane; }
        bind "Alt t" { NewTab; }
    }
    locked {
        bind "Ctrl g" { SwitchToMode "Normal"; }
    }
}

Keep the default keybindings nearby when editing custom bindings:

zellij setup --dump-config | less

Command-line overrides

zellij options can override config values when starting Zellij:

zellij options --theme kanagawa --pane-frames true --mouse-mode true

Use command-line overrides for temporary experiments. Put stable preferences in config.kdl.

Config file​

Root options​

Theme​

Custom theme​

Keybindings​

Command-line overrides​