kovidgoyal/kitty · warning · SystemExit

usage: kitty +launch script.py [arguments to be passed to sc

Error message

usage: kitty +launch script.py [arguments to be passed to script.py ...]\n\nscript.py will be run with full access to kitty code. If script.py is prefixed with a : it will be searched for in PATH. If script.py is a directory the __main__.py file inside it is run just as with the normal Python interpreter.

What it means

The kitty +launch entry point prints its usage and exits (SystemExit) when no script argument is given (args[1] missing).

Source

Thrown at kitty/entry_points.py:64

    os.execvp(kitten_exe(), args)


def open_urls(args: list[str]) -> None:
    setattr(sys, 'cmdline_args_for_open', True)
    sys.argv = ['kitty'] + args[1:]
    from kitty.main import main as kitty_main

    kitty_main()


def launch(args: list[str]) -> None:
    import runpy

    sys.argv = args[1:]
    try:
        exe = args[1]
    except IndexError:
        raise SystemExit(
            'usage: kitty +launch script.py [arguments to be passed to script.py ...]\n\n'
            'script.py will be run with full access to kitty code. If script.py is '
            'prefixed with a : it will be searched for in PATH. If script.py is a directory '
            'the __main__.py file inside it is run just as with the normal Python interpreter.'
        )
    if exe.startswith(':'):
        import shutil

        q = shutil.which(exe[1:])
        if not q:
            raise SystemExit(f'{exe[1:]} not found in PATH')
        exe = q
    if not os.path.exists(exe):
        raise SystemExit(f'{exe} does not exist')
    runpy.run_path(exe, run_name='__main__')


def shebang(args: list[str]) -> None:

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Pass the script: kitty +launch script.py
2. Use :name form to resolve from PATH
3. Verify the script variable is set in wrapper scripts

Example fix

# before
kitty +launch
# after
kitty +launch :my-kitty-script arg1

import sys
if len(sys.argv) < 2 or not sys.argv[1]:
    sys.exit('usage: kitty +launch script.py [args ...]')

When it happens

Trigger: Running `kitty +launch` with no script path.

Common situations: Empty script variable in wrapper scripts, or misunderstanding that +launch requires an explicit script path. A leading ':' searches PATH; directories run their __main__.py.

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 +runpy "some python code"
• No kitten named {original_kitten_name}
• This should be run as kitten ssh
• This should be run as kitten unicode_input
• Unknown type_of_input: {type_of_input}

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