kovidgoyal/kitty · warning

The option {key} is deprecated. Use hide_window_decorations

Error message

The option {key} is deprecated. Use hide_window_decorations instead.

What it means

macos_hide_titlebar / x11_hide_window_decorations (and related aliases) are deprecated; kitty logs this once per key and maps them to hide_window_decorations where appropriate. The log line uses {key} without .format in the deprecation branch path shown, producing the literal placeholder in the message text.

Source

Thrown at kitty/options/utils.py:1871

        return ()
    ans: list[tuple[Color, float]] = []
    seen: dict[Color, int] = {}
    for part in spec.split():
        col, sep, alpha = part.partition('@')
        c = to_color(col)
        o = max(-1, min(float(alpha) if alpha else -1, 1))
        if (idx := seen.get(c)) is not None:
            ans[idx] = c, o
            continue
        seen[c] = len(ans)
        ans.append((c, o))
    return tuple(ans[:7])


def deprecated_hide_window_decorations_aliases(key: str, val: str, ans: dict[str, Any]) -> None:
    if not hasattr(deprecated_hide_window_decorations_aliases, key):
        setattr(deprecated_hide_window_decorations_aliases, key, True)
        log_error(f'The option {key} is deprecated. Use hide_window_decorations instead.')
    if to_bool(val):
        if is_macos and key == 'macos_hide_titlebar' or (not is_macos and key == 'x11_hide_window_decorations'):
            ans['hide_window_decorations'] = True


def deprecated_macos_show_window_title_in_menubar_alias(key: str, val: str, ans: dict[str, Any]) -> None:
    if not hasattr(deprecated_macos_show_window_title_in_menubar_alias, key):
        setattr(deprecated_macos_show_window_title_in_menubar_alias, 'key', True)
        log_error(f'The option {key} is deprecated. Use macos_show_window_title_in menubar instead.')
    macos_show_window_title_in = ans.get('macos_show_window_title_in', 'all')
    if to_bool(val):
        if macos_show_window_title_in == 'none':
            macos_show_window_title_in = 'menubar'
        elif macos_show_window_title_in == 'window':
            macos_show_window_title_in = 'all'
    else:
        if macos_show_window_title_in == 'all':
            macos_show_window_title_in = 'window'

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Replace with hide_window_decorations yes|no|titlebar-only (macOS alias: system).
2. Remove macos_hide_titlebar and x11_hide_window_decorations lines.
3. Ignore the warning harmlessly if you cannot edit the config yet.

Example fix

# before
macos_hide_titlebar yes

# after
hide_window_decorations titlebar-only

def uses_deprecated_hide_decorations(cfg: str) -> bool:
    return 'macos_hide_titlebar' in cfg or 'x11_hide_window_decorations' in cfg

def uses_deprecated_hide_decorations(cfg: str) -> bool:
    return 'macos_hide_titlebar' in cfg or 'x11_hide_window_decorations' in cfg

When it happens

Trigger: Having 'macos_hide_titlebar yes' or 'x11_hide_window_decorations yes' in kitty.conf on any platform; the warning fires once per deprecated key per process due to a function-attribute memoization.

Common situations: Old configs from kitty <0.14-ish era; tutorials still recommending the old options.

Related errors

• The option {key} is deprecated. Use macos_show_window_title_
• Send text: {val} is invalid ({msg}), ignoring
• Percentage adjustments of {key} must be positive numbers
• The option {key} is deprecated. Use scrollbar instead.
• This should be run as kitten broadcast

AI-assisted analysis of kovidgoyal/kitty@6d5d0c4406 (2026-08-27). Data as JSON: /api/errors/462d341405a7601f. Report an issue: GitHub.