gitdesktoplinux.com
yehudah/desktop ↗

GitHub Desktop Linux troubleshooting

Most problems with GitHub Desktop on Linux come down to four things: the sign-in link handler, the keyring, FUSE for the AppImage, and the Chromium sandbox. Find your symptom below; each fix has the command to check it.

Sign-in: the browser approves but nothing happens

After you approve GitHub Desktop in the browser, GitHub redirects to an x-github-client:// link. Your desktop must know that GitHub Desktop handles that link. Check:

shell
xdg-mime query default x-scheme-handler/x-github-client
  • .deb: it should print github-desktop.desktop. If it prints nothing, install desktop-file-utils and rebuild the MIME cache:
    shell
    sudo apt install desktop-file-utils
sudo update-desktop-database /usr/share/applications
  • AppImage: a bare AppImage registers nothing. Create the launcher from the AppImage guide (step 5), or integrate it with AppImageLauncher or Gear Lever.
  • If another app is already the default for this link type, GitHub Desktop leaves it alone. Set it explicitly:
    shell
    xdg-mime default github-desktop.desktop x-scheme-handler/x-github-client

Test the handler without signing in. This should open GitHub Desktop's Clone dialog:

shell
xdg-open 'x-github-client://openRepo/https://github.com/desktop/desktop'

Also expected: the GitHub authorization page shows the name of GitHub Desktop's development OAuth app. Unofficial builds can't use GitHub's production app credentials, so this is normal, not a sign of a fake page. Check that the address bar says github.com.

Signed out after every restart, or "not signed in"

GitHub Desktop stores your token through the Secret Service API. If no keyring is running, or it is locked, saving the token fails and the app later looks signed out. Fix it by running a keyring that is unlocked at login:

  • GNOME, Cinnamon, MATE, Xfce, Budgie: install gnome-keyring and log out and back in.
  • KeePassXC users: enable Settings → Secret Service Integration and keep the database unlocked while you use GitHub Desktop.
  • Window managers (i3, Sway, Hyprland): start gnome-keyring-daemon from your session or via PAM, so it unlocks with your login password.

Check that a Secret Service provider is on the session bus:

shell
busctl --user list | grep org.freedesktop.secrets

No output means no provider is running. After fixing it, sign in again once.

AppImage won't start: libfuse.so.2 missing

An error like dlopen(): error loading libfuse.so.2 means FUSE 2 is not installed.

shell
sudo apt install libfuse2t64   # Ubuntu 24.04 / Debian 13
sudo apt install libfuse2      # Ubuntu 22.04 / Debian 12
sudo dnf install fuse-libs     # Fedora
sudo pacman -S --needed fuse2  # Arch

Or skip FUSE entirely:

shell
./GitHubDesktop-linux-x86_64-*.AppImage --appimage-extract-and-run

If it starts and then fails with a missing .so library, install the desktop libraries listed in the AppImage requirements. Messages about libappindicator, libgconf-2 or libindicator only affect the tray icon and can be ignored.

Sandbox errors and --no-sandbox

Errors mentioning the "SUID sandbox helper" or "No usable sandbox" mean Chromium's sandbox could not start.

  • .deb on Ubuntu 24.04: the system AppArmor profile only covers /usr/lib/github-desktop. Don't move or copy the install elsewhere. Reinstall the package if you did.
  • AppImage on Ubuntu 24.04: expected. Start it with --no-sandbox, as the AppImage guide does, or use the .deb, which runs sandboxed.

Running GitHub Desktop in Docker

Docker's default seccomp profile blocks the calls the sandbox needs. Start the container with --security-opt seccomp=unconfined or --cap-add SYS_ADMIN, or run the app with --no-sandbox inside a throwaway container. You also need an X11 or Wayland display passed through.

GLIBC_2.34 not found

The bundled git needs glibc 2.34 or newer. Ubuntu 20.04 (glibc 2.31) and Debian 11 (glibc 2.31) are too old, and there is no workaround short of upgrading the OS. Check your version with ldd --version.

Exec format error (ARM)

Builds exist only for 64-bit x86_64. On ARM devices (Raspberry Pi, ARM laptops) the files can't run. uname -m must print x86_64.

Blurry window or rendering problems on Wayland

This is general Electron advice rather than something specific to this build. If the window is blurry with fractional scaling, or flickers, try forcing a display backend when you start the app, and keep the flag that works in your launcher:

shell
github-desktop --ozone-platform=wayland   # native Wayland
github-desktop --ozone-platform=x11       # through XWayland

The app says it can't check for updates

The built-in updater only works for official Windows and macOS builds. On Linux, watch the changelog or the GitHub releases page and install new versions yourself; with the .deb, apt upgrades in place.

Still stuck?

Search or open an issue on the fork's issue tracker. Include your distribution and version, whether you use the .deb or AppImage, and the output of github-desktop started from a terminal. Please don't report Linux build problems to the official GitHub Desktop project.