{"record":{"id":"4a222e7e6b95e12b","repo":"kovidgoyal/kitty","slug":"failed-to-find-libxkbcommon","errorCode":null,"errorMessage":"Failed to find libxkbcommon","messagePattern":"Failed to find libxkbcommon","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"kitty/key_names.py","lineNumber":79,"sourceCode":"if is_macos:\n\n    def get_key_name_lookup() -> LookupFunc:\n        return null_lookup\nelse:\n\n    def load_libxkb_lookup() -> LookupFunc:\n        import ctypes\n\n        for suffix in ('.0', ''):\n            with suppress(Exception):\n                lib = ctypes.CDLL(f'libxkbcommon.so{suffix}')\n                break\n        else:\n            from ctypes.util import find_library\n\n            lname = find_library('xkbcommon')\n            if lname is None:\n                raise RuntimeError('Failed to find libxkbcommon')\n            lib = ctypes.CDLL(lname)\n\n        f = lib.xkb_keysym_from_name\n        f.argtypes = [ctypes.c_char_p, ctypes.c_int]\n        f.restype = ctypes.c_int\n\n        def xkb_lookup(name: str, case_sensitive: bool = False) -> int | None:\n            q = name.encode('utf-8')\n            return f(q, int(case_sensitive)) or None\n\n        return xkb_lookup\n\n    def get_key_name_lookup() -> LookupFunc:\n        ans: LookupFunc | None = getattr(get_key_name_lookup, 'ans', None)\n        if ans is None:\n            try:\n                ans = load_libxkb_lookup()\n            except Exception as e:","sourceCodeStart":61,"sourceCodeEnd":97,"githubUrl":"https://github.com/kovidgoyal/kitty/blob/6d5d0c440603ad9bdf6dcd599f73f6dde21acb44/kitty/key_names.py#L61-L97","documentation":"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.","triggerScenarios":"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).","commonSituations":"Minimal/container images (Alpine, slim Debian) without libxkbcommon0; broken ldconfig; NixOS/nonstandard lib dirs; stripping runtime deps in packaging.","solutions":["Install libxkbcommon (apt install libxkbcommon0 / apk add libxkbcommon / dnf install libxkbcommon).","Run ldconfig and verify: find_library via python -c \"from ctypes.util import find_library; print(find_library('xkbcommon'))\".","In containers, ensure the runtime image (not just the build image) includes the library."],"exampleFix":"# before (Dockerfile)\nFROM python:3.12-slim\n# after\nFROM python:3.12-slim\nRUN apt-get update && apt-get install -y libxkbcommon0 && rm -rf /var/lib/apt/lists/*","handlingStrategy":"fallback","validationCode":"from ctypes.util import find_library\nif find_library('xkbcommon') is None:\n    raise RuntimeError('install libxkbcommon before using key-name lookup')","typeGuard":null,"tryCatchPattern":"try:\n    lookup = get_key_name_lookup()\nexcept (RuntimeError, OSError):\n    lookup = None  # degrade gracefully without xkb names","preventionTips":["Include libxkbcommon in container/base images.","Verify with find_library in smoke tests after deployment."],"tags":["kitty","native-library","xkbcommon","environment"],"backgroundTag":"missing-native-library","analyzedSha":"6d5d0c440603ad9bdf6dcd599f73f6dde21acb44","analyzedAt":"2026-08-27T14:20:20.142Z","schemaVersion":2},"datasetVersion":"2026-08-27T19:17:21.184Z"}