kovidgoyal/kitty · error · RuntimeError

kitty binary not found

Error message

kitty binary not found

What it means

constants.kitty_exe locates the kitty binary by scanning candidate dirs; if none contains an executable named 'kitty' it raises RuntimeError('kitty binary not found'). Many helpers (kitten_exe, kitty_shell, exec_under_perf, docs) depend on it.

Source

Thrown at kitty/constants.py:100

else:
    kitty_base_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
    extensions_dir = os.path.join(kitty_base_dir, 'kitty')


@run_once
def kitty_exe() -> str:
    rpath = kitty_run_data.get('bundle_exe_dir')
    if not rpath:
        items = os.environ.get('PATH', '').split(os.pathsep) + [os.path.join(kitty_base_dir, 'kitty', 'launcher')]
        seen: set[str] = set()
        for candidate in filter(None, items):
            if candidate not in seen:
                seen.add(candidate)
                if os.access(os.path.join(candidate, 'kitty'), os.X_OK):
                    rpath = candidate
                    break
        else:
            raise RuntimeError('kitty binary not found')
    return os.path.join(rpath, 'kitty')


@run_once
def kitten_exe() -> str:
    return os.path.join(os.path.dirname(kitty_exe()), 'kitten')


def _get_config_dir() -> str:
    cdir = kitty_run_data.get('config_dir', '')
    if cdir:
        return str(cdir)
    import atexit
    import tempfile

    ans = tempfile.mkdtemp(prefix='kitty-conf-')

    def cleanup() -> None:

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Install kitty properly (make && sudo make install) so the binary exists next to the python code
2. Run from an installed kitty rather than a bare checkout
3. If developing, build the kitty binary in the checkout first
4. Ensure the kitty dir isn't stripped by packaging

Example fix

# before
# running kitten from source clone without build
git clone kitty && kitten icat img.png
# after
cd kitty && make
./kitten icat img.png

import shutil
kitty_ok = shutil.which('kitty') is not None

from kitty.constants import kitty_exe
try:
    exe = kitty_exe()
except RuntimeError:
    exe = shutil.which('kitty') or '/usr/local/bin/kitty'

When it happens

Trigger: kitty's python code running from a source checkout or unusual install where no runnable 'kitty' executable exists in the searched locations; or a broken package where the binary was stripped.

Common situations: Running kittens/tests from a git clone without building, pip/npm-style installs that omit the launcher, or PATH/venv setups that shadow kitty.

Related errors

• This must be run as kitten ask
• This should be run as kitten broadcast
• This must be run as kitten choose-files
• Pipe to kitten was broken while sending data to it
• Unknown action: {action}

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