kovidgoyal/kitty · error · SystemExit

This must be run as kitten themes

Error message

This must be run as kitten themes

What it means

The themes kitten's main() is a deliberate stub: it always raises SystemExit('This must be run as kitten themes'). The real functionality is provided by kitty's kitten runner (the '__doc__'/cli_docs machinery shown in the source); executing the module directly as __main__ can only reach the stub.

Source

Thrown at kittens/themes/main.py:112

--dump-theme
type=bool-set
default=false
When running non-interactively, dump the specified theme to STDOUT
instead of changing kitty.conf.


--config-file-name
default=kitty.conf
The name or path to the config file to edit. Relative paths are interpreted
with respect to the kitty config directory. By default the kitty config file,
kitty.conf is edited. This is most useful if you add :code:`include themes.conf`
to your kitty.conf and then have the kitten operate only on :file:`themes.conf`,
allowing :code:`kitty.conf` to remain unchanged.
""".format


def main(args: list[str]) -> None:
    raise SystemExit('This must be run as kitten themes')


if __name__ == '__main__':
    main(sys.argv)
elif __name__ == '__doc__':
    cd = sys.cli_docs  # type: ignore
    cd['usage'] = usage
    cd['options'] = OPTIONS
    cd['help_text'] = help_text
    cd['short_desc'] = 'Manage kitty color schemes easily'
    cd['args_completion'] = CompletionSpec.from_string('type:special group:complete_themes')
elif __name__ == '__conf__':
    sys.options_definition = definition  # type: ignore

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Run `kitten themes` from inside a kitty window (or map a key: map f1 launch --type=overlay kitten themes).
2. For programmatic theme manipulation, edit the theme files in ~/.config/kitty/themes or use kitty's remote-control/set-colors API instead of the stub main().
3. In tests, import and exercise the theme-loading helpers, not main().

Example fix

# before
python kittens/themes/main.py  # SystemExit: This must be run as kitten themes

# after
kitten themes

import os

def can_run_kitten() -> bool:
    return bool(os.environ.get('KITTY_WINDOW_ID')) and bool(shutil.which('kitten'))

if not can_run_kitten():
    raise SystemExit('themes kitten requires kitty; run: kitten themes')

When it happens

Trigger: Running `python kittens/themes/main.py` directly, or importing kittens/themes/main.py and calling main(args). Works correctly only when launched via `kitten themes` inside kitty.

Common situations: Source-diving and executing the file with python/IDE run; scripts calling main() programmatically; attempting to use the theme browser outside kitty (e.g. in gnome-terminal), where it cannot work anyway.

Related errors

• This should be run as kitten show_key
• This should be run as kitten transfer
• No kitten named {original_kitten_name}
• This should be run as kitten ssh
• Remote control not enabled, this kitten should be run via a

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