{"record":{"id":"2fb9b652a65c5ce4","repo":"kovidgoyal/kitty","slug":"failed-to-enable-transparency-this-happens-when-y","errorCode":null,"errorMessage":"Failed to enable transparency. This happens when your desktop environment does not support compositing.","messagePattern":"Failed to enable transparency\\. This happens when your desktop environment does not support compositing\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"kitty/glfw.c","lineNumber":2271,"sourceCode":"    glfwSetCursorPosCallback(glfw_window, cursor_pos_callback);\n    glfwSetCursorEnterCallback(glfw_window, cursor_enter_callback);\n    glfwSetScrollCallback(glfw_window, scroll_callback);\n    glfwSetKeyboardCallback(glfw_window, key_callback);\n\n    glfwSetDragSourceCallback(glfw_window, drag_source_callback);\n    glfwSetDropEventCallback(glfw_window, drop_dest_callback);\n    monotonic_t now = monotonic();\n    w->is_focused = true;\n    w->shader_anim_event_registry |= (1u << SHADER_ANIM_EVENT_OS_WINDOW_FOCUS_IN) | (1u << SHADER_ANIM_EVENT_WINDOW_FOCUS_IN);\n    w->cursor_blink_zero_time = now;\n    w->last_mouse_activity_at = now;\n    w->mouse_activate_deadline = -1;\n    w->mouse_show_threshold = 0;\n    w->background_opacity.supports_transparency = is_semi_transparent;\n    if (want_semi_transparent && !w->background_opacity.supports_transparency) {\n        static bool warned = false;\n        if (!warned) {\n            log_error(\"Failed to enable transparency. This happens when your desktop environment does not support compositing.\");\n            warned = true;\n        }\n    }\n    init_window_chrome_state(&w->last_window_chrome, OPT(background), effective_os_window_alpha(w));\n    if (w->is_layer_shell) {\n        if (global_state.is_apple) set_layer_shell_config_for(w, lsc);\n    } else apply_window_chrome_state(w->handle, w->last_window_chrome, width, height, global_state.is_apple ? OPT(hide_window_decorations) != 0 : false);\n#ifdef __APPLE__\n    if (!w->is_layer_shell) glfwCocoaSetWindowLevel(w->handle, OPT(macos_ns_window_layer));\n#endif\n    // Update window state\n    // We do not call glfwWindowHint to set GLFW_MAXIMIZED before the window is created.\n    // That would cause the window to be set to maximize immediately after creation and use the wrong initial size when restored.\n    if (window_state != WINDOW_NORMAL) change_state_for_os_window(w, window_state);\n#ifdef __APPLE__\n    // macOS: Show the window after it is ready\n    if (window_state != WINDOW_HIDDEN) glfwShowWindow(glfw_window, false);\n#endif","sourceCodeStart":2253,"sourceCodeEnd":2289,"githubUrl":"https://github.com/kovidgoyal/kitty/blob/6d5d0c440603ad9bdf6dcd599f73f6dde21acb44/kitty/glfw.c#L2253-L2289","documentation":"Kitty requested a semi-transparent background (background_opacity < 1.0) but the window system reported the window is not actually composited with alpha support. This occurs when the desktop environment lacks a compositing manager or the window is created in a mode where transparency cannot be honored (e.g. certain X11 setups without a compositor running). It is logged once (static warned flag) because every window creation would otherwise repeat it.","triggerScenarios":"Setting background_opacity to a value < 1.0 in kitty.conf while running on X11 without a compositor (no picom/xfwm compositing), or on a framebuffer/headless session, or with --override background_opacity=0.9 on an environment where is_semi_transparent evaluates false at window creation.","commonSituations":"Starting kitty on a minimal X11 WM (i3, dwm) without picom/compton running; running kitty inside some VNC or Xephyr sessions; WSLg edge cases; users copying configs with background_blur + background_opacity to machines without compositing.","solutions":["Start a compositor (e.g. run picom, or enable compositing in your WM/desktop settings) and restart kitty","Set background_opacity 1.0 in kitty.conf to acknowledge opacity is unsupported","On Wayland, ensure a compositor that supports alpha (most do); check you are not forcing X11 via GLFW_PLATFORM or XDG_SESSION_TYPE","If using a tiling WM, add picom to your startup script"],"exampleFix":"# before (kitty.conf)\nbackground_opacity 0.85\n# after\nbackground_opacity 1.0\n# or start a compositor before kitty:\npicom -b & kitty","handlingStrategy":"validation","validationCode":"# shell check before launching kitty with transparency\nif [ \"$XDG_SESSION_TYPE\" = \"x11\" ] && ! pgrep -x picom >/dev/null && ! pgrep -x compton >/dev/null; then\n  sed -i 's/^background_opacity .*/background_opacity 1.0/' ~/.config/kitty/kitty.conf\nfi","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep a compositor (picom) in your WM startup chain if you use background_opacity < 1","Gate transparency settings per-host instead of syncing one kitty.conf everywhere","Treat this log as a warning: kitty continues with an opaque background"],"tags":["kitty","transparency","compositing","x11","wayland","window"],"backgroundTag":"compositor-transparency-unsupported","analyzedSha":"6d5d0c440603ad9bdf6dcd599f73f6dde21acb44","analyzedAt":"2026-08-27T14:20:20.142Z","schemaVersion":2},"datasetVersion":"2026-08-27T19:17:21.184Z"}