kovidgoyal/kitty · error · OpacityError

You must turn on the dynamic_background_opacity option in ki

Error message

You must turn on the dynamic_background_opacity option in kitty.conf to be able to set background opacity

What it means

set-background-opacity requires the dynamic_background_opacity option to be enabled in kitty.conf because runtime opacity changes are only honored when that option is on.

Source

Thrown at kitty/rc/set_background_opacity.py:76

    )
    args = RemoteCommand.Args(spec='OPACITY', count=1, json_field='opacity', special_parse='parse_opacity(args[0])')

    def message_to_kitty(self, global_opts: RCOptions, opts: 'CLIOptions', args: ArgsType) -> PayloadType:
        opacity = max(0, min(float(args[0]), 1))
        return {
            'opacity': opacity,
            'match_window': opts.match,
            'all': opts.all,
            'match_tab': opts.match_tab,
            'toggle': opts.toggle,
        }

    def response_from_kitty(self, boss: Boss, window: Window | None, payload_get: PayloadGetType) -> ResponseType:
        from kitty.fast_data_types import background_opacity_of, get_options

        opts = get_options()
        if not opts.dynamic_background_opacity:
            raise OpacityError('You must turn on the dynamic_background_opacity option in kitty.conf to be able to set background opacity')
        windows = self.windows_for_payload(boss, window, payload_get)
        for os_window_id in {w.os_window_id for w in windows if w}:
            val: float = payload_get('opacity') or 0.0
            if payload_get('toggle'):
                current = background_opacity_of(os_window_id)
                # GLFW represents opacity as a float internally, but python's
                # "float" type has double precision, so we can't rely on precise
                # equality here
                if current is not None and abs(current - val) <= 0.0001:
                    val = opts.background_opacity
            boss._set_os_window_background_opacity(os_window_id, val)
        return None


set_background_opacity = SetBackgroundOpacity()

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Add 'dynamic_background_opacity yes' to kitty.conf and restart kitty
2. Then re-run kitten @set-background-opacity <value>

Example fix

# kitty.conf
dynamic_background_opacity yes

from kitty.config import load_config
assert load_config().dynamic_background_opacity

When it happens

Trigger: Running kitten @set-background-opacity without 'dynamic_background_opacity yes' in kitty.conf.

Common situations: Users adding opacity scripts (fades, dim inactive windows) without enabling the prerequisite config option.

Related errors

• This should be run as kitten broadcast
• No option named: {k}
• No custom kitten named {kitten} found
• Not a number: {x} with error: {e}
• Not a valid unit: {x}. Allowed units are: {default_unit}, {"

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