kovidgoyal/kitty · info

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

Error message

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

What it means

This error is logged when a deprecated scrollback indicator opacity option (e.g. scrollback_indicator_opacity) is set in kitty.conf. kitty maps these legacy options onto the new scrollbar options, and logs a deprecation warning once per option key via a function-attribute guard.

Source

Thrown at kitty/options/utils.py:1926

def deprecated_adjust_line_height(key: str, x: str, opts_dict: dict[str, Any]) -> None:
    fm = {'adjust_line_height': 'cell_height', 'adjust_baseline': 'baseline', 'adjust_column_width': 'cell_width'}[key]
    mtype = getattr(ModificationType, fm)
    if x.endswith('%'):
        ans = float(x[:-1].strip())
        if ans < 0:
            log_error(f'Percentage adjustments of {key} must be positive numbers')
            return
        opts_dict['modify_font'][fm] = FontModification(mtype, ModificationValue(ans, ModificationUnit.percent))
    else:
        opts_dict['modify_font'][fm] = FontModification(mtype, ModificationValue(int(x), ModificationUnit.pixel))


def deprecated_scrollback_indicator_opacity(key: str, val: str, ans: dict[str, Any]) -> None:
    if not hasattr(deprecated_scrollback_indicator_opacity, key):
        setattr(deprecated_scrollback_indicator_opacity, key, True)
        log_error(f'The option {key} is deprecated. Use scrollbar instead.')
    op = unit_float(val)
    if op <= 0.001:
        ans['scrollbar'] = 'never'
    else:
        ans['scrollbar_handle_opacity'] = op

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Remove scrollback_indicator_opacity from kitty.conf and use scrollbar and scrollbar_handle_opacity instead
2. Run kitten choices or kitty --config to find which file/line still sets the deprecated option
3. Alias migration: value <= 0.001 maps to scrollbar never; otherwise set scrollbar_handle_opacity to the same float

Example fix

# before
scrollback_indicator_opacity 0.75

# after
scrollbar auto
scrollbar_handle_opacity 0.75

# before shipping a config, check for deprecated keys
import re
bad = [l for l in open('kitty.conf') if re.match(r'\s*scrollback_indicator_opacity', l)]
assert not bad, bad

When it happens

Trigger: Setting scrollback_indicator_opacity (or related deprecated keys) in kitty.conf or via a config include; the option parser deprecated_scrollback_indicator_opacity runs and logs once per key.

Common situations: Copying old configs from tutorials or older kitty versions into a newer kitty install (scrollbar replaced scrollback_indicator_opacity).

Related errors

• The value {val} is not a valid choice for scrollbar
• The option {key} is deprecated. Use hide_window_decorations
• 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

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