kovidgoyal/kitty · error · RuntimeError

Failed to find libxkbcommon

Error message

Failed to find libxkbcommon

What it means

kitty's key-name translation uses libxkbcommon via ctypes. load_libxkb_lookup first tries a list of known sonames, then falls back to ctypes.util.find_library('xkbcommon'); if that also fails, RuntimeError('Failed to find libxkbcommon') is raised.

Source

Thrown at kitty/key_names.py:79

if is_macos:

    def get_key_name_lookup() -> LookupFunc:
        return null_lookup
else:

    def load_libxkb_lookup() -> LookupFunc:
        import ctypes

        for suffix in ('.0', ''):
            with suppress(Exception):
                lib = ctypes.CDLL(f'libxkbcommon.so{suffix}')
                break
        else:
            from ctypes.util import find_library

            lname = find_library('xkbcommon')
            if lname is None:
                raise RuntimeError('Failed to find libxkbcommon')
            lib = ctypes.CDLL(lname)

        f = lib.xkb_keysym_from_name
        f.argtypes = [ctypes.c_char_p, ctypes.c_int]
        f.restype = ctypes.c_int

        def xkb_lookup(name: str, case_sensitive: bool = False) -> int | None:
            q = name.encode('utf-8')
            return f(q, int(case_sensitive)) or None

        return xkb_lookup

    def get_key_name_lookup() -> LookupFunc:
        ans: LookupFunc | None = getattr(get_key_name_lookup, 'ans', None)
        if ans is None:
            try:
                ans = load_libxkb_lookup()
            except Exception as e:

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Install libxkbcommon (apt install libxkbcommon0 / apk add libxkbcommon / dnf install libxkbcommon).
2. Run ldconfig and verify: find_library via python -c "from ctypes.util import find_library; print(find_library('xkbcommon'))".
3. In containers, ensure the runtime image (not just the build image) includes the library.

Example fix

# before (Dockerfile)
FROM python:3.12-slim
# after
FROM python:3.12-slim
RUN apt-get update && apt-get install -y libxkbcommon0 && rm -rf /var/lib/apt/lists/*

from ctypes.util import find_library
if find_library('xkbcommon') is None:
    raise RuntimeError('install libxkbcommon before using key-name lookup')

try:
    lookup = get_key_name_lookup()
except (RuntimeError, OSError):
    lookup = None  # degrade gracefully without xkb names

When it happens

Trigger: Calling get_key_name_lookup on a system where none of the bundled sonames load and find_library returns None — libxkbcommon not installed or not on the loader search path (LD_LIBRARY_PATH, ldconfig cache).

Common situations: Minimal/container images (Alpine, slim Debian) without libxkbcommon0; broken ldconfig; NixOS/nonstandard lib dirs; stripping runtime deps in packaging.

Related errors

• {path} is not a supported shell
• Failed to find the kitty executable, this kitten requires th
• could not connect to session D-Bus: %s
• failed to connect to system bus with error: %w
• Failed to parse rg help output, could not find any options

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