kovidgoyal/kitty · warning · SystemExit

Usage: kitty +runpy "some python code"

Error message

Usage: kitty +runpy "some python code"

What it means

The kitty +runpy entry point requires the python code as the first argument; with fewer than 2 args it prints usage and exits via SystemExit.

Source

Thrown at kitty/entry_points.py:23

import os
import sys


def icat(args: list[str]) -> None:
    from kitty.constants import kitten_exe

    os.execl(kitten_exe(), 'kitten', *args)


def list_fonts(args: list[str]) -> None:
    from kitty.fonts.list import main as list_main

    list_main(args)


def runpy(args: list[str]) -> None:
    if len(args) < 2:
        raise SystemExit('Usage: kitty +runpy "some python code"')
    sys.argv = ['kitty'] + args[2:]
    exec(args[1])


def hold(args: list[str]) -> None:
    from kitty.constants import kitten_exe

    args = ['kitten', '__hold_till_enter__'] + args[1:]
    os.execvp(kitten_exe(), args)


def complete(args: list[str]) -> None:
    # Delegate to kitten to maintain backward compatibility
    if len(args) < 2 or args[1] not in ('setup', 'zsh', 'fish2', 'bash'):
        raise SystemExit(1)
    if args[1] == 'fish2':
        args[1:1] = ['fish', '_legacy_completion=fish2']
    elif len(args) >= 3 and args[1:3] == ['setup', 'fish2']:

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Pass the code: kitty +runpy "print(1)"
2. Quote the code so it arrives as a single argv element
3. Check the variable expansion in scripts before invoking

Example fix

# before
kitty +runpy
# after
kitty +runpy "import kitty; print(kitty.__version__)"

import sys
code = sys.argv[1] if len(sys.argv) > 1 else None
if not code:
    sys.exit('Usage: kitty +runpy "some python code"')
runpy_entry(['kitty', code])

When it happens

Trigger: Running `kitty +runpy` with no python code argument.

Common situations: Shell scripts where the code string variable is empty/unset due to quoting mistakes.

Understand the failure class

Background: "no subcommand specified" and "... is required": CLI errors when a required argument is missing — this error's family across 13 libraries.

Related errors

• usage: kitty +launch script.py [arguments to be passed to sc
• No kitten named {original_kitten_name}
• This should be run as kitten ssh
• This should be run as kitten unicode_input
• {x} is not a valid value for {alias}. Valid values are y, ye

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