AppImage not running on CachyOS because of no running X server

[rjspies]

To Reproduce

Steps to reproduce the behavior:

1. Install app via AppImageLauncher
2. Run app
3. ???
4. Read journalctl

Environment

• OS: [CachyOS]
• Desktop: [KDE]
• Display Server: [Wayland]
• Python version: [3.14.3]
• Argus Overview version: [3.0.4]

Logs

Journal

Apr 04 15:01:25 harley Argus-Overview-v3.1.0-x86_64_95f609f1690021144c7c0bf2ff721e9f.AppImage[85811]: 2026-04-04 15:01:25,932 - argus_overview.utils.display_server - INFO - Display detection: XDG_SESSION_TYPE=wayland, WAYLAND_DISPLAY=wayland-0, DISPLAY=:0
Apr 04 15:01:25 harley Argus-Overview-v3.1.0-x86_64_95f609f1690021144c7c0bf2ff721e9f.AppImage[85811]: 2026-04-04 15:01:25,932 - argus_overview.utils.display_server - INFO - Detected display server: xwayland, X11 access: True
Apr 04 15:01:25 harley Argus-Overview-v3.1.0-x86_64_95f609f1690021144c7c0bf2ff721e9f.AppImage[85811]: 2026-04-04 15:01:25,932 - __main__ - INFO - Running under XWayland - X11 tools available, full functionality expected
Apr 04 15:01:25 harley Argus-Overview-v3.1.0-x86_64_95f609f1690021144c7c0bf2ff721e9f.AppImage[85811]: Traceback (most recent call last):
Apr 04 15:01:25 harley Argus-Overview-v3.1.0-x86_64_95f609f1690021144c7c0bf2ff721e9f.AppImage[85811]:   File "main.py", line 256, in <module>
Apr 04 15:01:25 harley Argus-Overview-v3.1.0-x86_64_95f609f1690021144c7c0bf2ff721e9f.AppImage[85811]:   File "main.py", line 232, in main
Apr 04 15:01:25 harley Argus-Overview-v3.1.0-x86_64_95f609f1690021144c7c0bf2ff721e9f.AppImage[85811]:   File "pyimod02_importers.py", line 457, in exec_module
Apr 04 15:01:25 harley Argus-Overview-v3.1.0-x86_64_95f609f1690021144c7c0bf2ff721e9f.AppImage[85811]:   File "argus_overview/ui/main_window_v21.py", line 57, in <module>
Apr 04 15:01:25 harley Argus-Overview-v3.1.0-x86_64_95f609f1690021144c7c0bf2ff721e9f.AppImage[85811]:   File "pyimod02_importers.py", line 457, in exec_module
Apr 04 15:01:25 harley Argus-Overview-v3.1.0-x86_64_95f609f1690021144c7c0bf2ff721e9f.AppImage[85811]:   File "argus_overview/core/hotkey_manager.py", line 6, in <module>
Apr 04 15:01:25 harley Argus-Overview-v3.1.0-x86_64_95f609f1690021144c7c0bf2ff721e9f.AppImage[85811]:   File "pyimod02_importers.py", line 457, in exec_module
Apr 04 15:01:25 harley Argus-Overview-v3.1.0-x86_64_95f609f1690021144c7c0bf2ff721e9f.AppImage[85811]:   File "pynput/__init__.py", line 40, in <module>
Apr 04 15:01:25 harley Argus-Overview-v3.1.0-x86_64_95f609f1690021144c7c0bf2ff721e9f.AppImage[85811]:   File "pyimod02_importers.py", line 457, in exec_module
Apr 04 15:01:25 harley Argus-Overview-v3.1.0-x86_64_95f609f1690021144c7c0bf2ff721e9f.AppImage[85811]:   File "pynput/keyboard/__init__.py", line 31, in <module>
Apr 04 15:01:25 harley Argus-Overview-v3.1.0-x86_64_95f609f1690021144c7c0bf2ff721e9f.AppImage[85811]:   File "pynput/_util/__init__.py", line 78, in backend
Apr 04 15:01:25 harley Argus-Overview-v3.1.0-x86_64_95f609f1690021144c7c0bf2ff721e9f.AppImage[85811]: ImportError: this platform is not supported: No module named 'pynput.keyboard._xorg'
Apr 04 15:01:25 harley Argus-Overview-v3.1.0-x86_64_95f609f1690021144c7c0bf2ff721e9f.AppImage[85811]: Try one of the following resolutions:
Apr 04 15:01:25 harley Argus-Overview-v3.1.0-x86_64_95f609f1690021144c7c0bf2ff721e9f.AppImage[85811]:  * Please make sure that you have an X server running, and that the DISPLAY environment variable is set correctly
Apr 04 15:01:25 harley Argus-Overview-v3.1.0-x86_64_95f609f1690021144c7c0bf2ff721e9f.AppImage[85811]: [PYI-85811:ERROR] Failed to execute script 'main' due to unhandled exception!
Apr 04 15:01:25 harley systemd[1321]: app-appimagekit_5b390b9e152b80f5616df8dc27feed05\x2dArgus_Overview@0c78f7b67b804e21ac7270b6606a38ef.service: Main process exited, code=exited, status=1/FAILURE
Apr 04 15:01:25 harley systemd[1]: tmp-.mount_Argus\x2d3oLzNi.mount: Deactivated successfully.
Apr 04 15:01:25 harley systemd[1321]: app-appimagekit_5b390b9e152b80f5616df8dc27feed05\x2dArgus_Overview@0c78f7b67b804e21ac7270b6606a38ef.service: Failed with result 'exit-code'.
Apr 04 15:01:25 harley systemd[1321]: app-appimagekit_5b390b9e152b80f5616df8dc27feed05\x2dArgus_Overview@0c78f7b67b804e21ac7270b6606a38ef.service: Consumed 584ms CPU time over 775ms wall clock time, 113.4M memory peak.

argus-overview.log

2026-04-04 15:01:25,853 - __main__ - INFO - Starting Argus Overview v3.0.4
2026-04-04 15:01:25,932 - argus_overview.utils.display_server - INFO - Display detection: XDG_SESSION_TYPE=wayland, WAYLAND_DISPLAY=wayland-0, DISPLAY=:0
2026-04-04 15:01:25,932 - argus_overview.utils.display_server - INFO - Detected display server: xwayland, X11 access: True
2026-04-04 15:01:25,932 - __main__ - INFO - Running under XWayland - X11 tools available, full functionality expected

[AreteDriver]

Fixed in working tree (pending commit). Guarded pynput import in hotkey_manager.py to degrade gracefully when X11 backend is unavailable (Wayland-only environments, AppImage without X11 libs). Follows the same try/except + PYNPUT_AVAILABLE pattern already used in hotkey_edit.py. All listener methods (start/stop/pause/resume/register) no-op safely when pynput is missing. Also expanded PyInstaller hidden imports in argus-overview.spec for better AppImage bundling (pynput._util, pynput._util.xorg, pynput._util.xorg_keysyms, Xlib.ext, Xlib.ext.xtest). All 2,179 tests pass.

[AreteDriver]

Thanks for the detailed logs — this is really helpful for diagnosing the root cause.

What's actually happening

This is not a display server access issue. The app correctly detects XWayland and DISPLAY=:0 is set. The real crash is deeper in the PyInstaller bundle:

ImportError: this platform is not supported: No module named 'pynput.keyboard._xorg'
Try one of the following resolutions:
  * Please make sure that you have an X server running, and that the DISPLAY environment variable is set correctly

pynput (used in hotkey_manager.py) ships separate backends for X11 (_xorg) and Wayland (_uinput). The AppImage bundle is missing pynput.keyboard._xorg — it wasn't included at PyInstaller build time, so even though XWayland is running, pynput has nothing to fall back on.

Workarounds to try

1. Run with pynput forced to its uinput/evdev backend (native Wayland, no XWayland needed):

   PYNPUT_BACKEND=uinput ./Argus_Overview.AppImage

2. Ensure DISPLAY is explicitly set (should already be the case, but worth confirming):

   DISPLAY=:0 ./Argus_Overview.AppImage

3. Install python-xlib system-wide — on CachyOS:

   sudo pacman -S python-xlib
   DISPLAY=:0 ./Argus_Overview.AppImage

   This may not help inside a frozen AppImage bundle but is worth trying.

Root cause for the maintainer

The PyInstaller .spec file needs to explicitly include the pynput X11 backend. In Argus_Overview.spec or wherever hidden imports are declared, add:

hiddenimports=[
    'pynput.keyboard._xorg',
    'pynput.mouse._xorg',
    # optionally for native Wayland:
    'pynput.keyboard._uinput',
    'pynput.mouse._uinput',
]

The display server detection in argus_overview/utils/display_server.py correctly identifies XWayland — the fix is upstream at bundle build time, not in the detection logic.

Environment note: CachyOS with KDE on Wayland + XWayland active — this is a very common setup and worth prioritizing.