ContextQMD
Back to Gitbutler

Linux compatibility

LINUX.md

0.19.105.2 KB
Original Source

Linux compatibility

GitButler should run well on most modern Linux distributions, but there are too many software and hardware combinations for the core team to support on its own. As such, the GitButler project maintains official support for a select few Linux distributions, and otherwise relies on community-maintained packages.

This document outlines the current level of commitment toward Linux distributions and packaging formats.

A more dynamic overview of the current state of Linux compatibility can be found in https://github.com/gitbutlerapp/gitbutler/issues/8411

Official support

The officially supported way to install GitButler is with the deb package provided on the downloads page. This package is regularly tested to work well with the following distributions.

  • Ubuntu 22.04 LTS (jammy)
  • Ubuntu 24.04 LTS (noble)

On these distributions, we aim to provide as good a user experience as on Windows and macOS. Compatibility is routinely verified and compatibility issues are the domain of the core GitButler team. We know that the current user experience does not quite deliver on all fronts, and work on improvements is underway.

This does not mean that the GitButler project is unconcerned with the woes of other Linux distributions. Reports of compatibility issues with any distribution are welcome in the issue tracker, but with the caveat that such issues are not guaranteed to get prioritized anytime soon. If there is a compatibility trade-off to be made, it will always be made in favor of the officially supported distributions.

Experimental distribution: rpm

We provide an experimental rpm package alongside the deb package. It is fundamentally the same thing as the deb package and should have the same level of compatibility, but it is not regularly tested on any distribution as part of the development process. We provide it as it is no extra effort to build with the current toolchain, and have no reason to believe it would come with any particular compatibility caveats.

Experimental distribution: AppImage

We provide an experimental AppImage that bundles the core dependencies required to run GitButler. The intention is that it should work on most Linux distributions, but experience shows that compatibility is relatively poor.

The AppImage may be removed in the future if compatibility remains poor.

Community-maintained distributions

There are several community-maintained distributions of GitButler. Issues with these distributions should typically be brought to the attention of their respective maintainers.

Know of one we missed? Submit a PR to keep us in the loop!

Known issues and workarounds

High CPU usage in WebKitGTK thread

If you're exhibiting high CPU usage in a WebKit-related thread, try disabling hardware acceleration for WebKitGTK.

bash
$ WEBKIT_DISABLE_COMPOSITING_MODE=1 gitbutler-tauri

See https://github.com/gitbutlerapp/gitbutler/issues/11602 for details.

Blank screen or crash with NVIDIA GPU

There are known incompatibilities between NVIDIA's proprietary drivers and WebKitGTK that may cause issues ranging from a blank screen to an immediate crash. These issues appear to be most prevalent on Wayland.

Known errors include:

  • KMS: DRM_IOCTL_MODE_CREATE_DUMB failed: Permission denied
    • Typically causes a blank screen
  • Error 71 (Protocol error) dispatching to Wayland display
    • Typically causes an immediate crash
    • Only visible if you run with the environment variable WAYLAND_DEBUG=1

There are a few workarounds to try:

  • Disable Explicit Sync with __NV_DISABLE_EXPLICIT_SYNC=1
    • If this works for you, it's the best known solution as it still allows the app to utilize your GPU
  • Disabling hardware acceleration with WEBKIT_DISABLE_COMPOSITING_MODE=1
    • Typically the most stable solution
    • The app will not run on your GPU which may cause performance degradation
  • Using the Nouveau driver instead of the proprietary NVIDIA driver
  • Using PRIME offloading so GitButler runs on your iGPU instead
    • You may still want to disable hardware acceleration due to performance issues

See https://github.com/gitbutlerapp/gitbutler/issues/11761 for details.

Blurry text with NVIDIA GPU

NVIDIA drivers have been known to cause blurry text in WebKitGTK-powered apps because of FXAA.

Workarounds to try:

  • Disabling hardware acceleration with WEBKIT_DISABLE_COMPOSITING_MODE=1
    • Typically the most stable solution
    • The app will not run on your GPU which may cause performance degradation
  • Disabling FXAA in NVIDIA settings
  • Using the Nouveau driver instead of the proprietary NVIDIA driver

See https://github.com/gitbutlerapp/gitbutler/issues/12971 for details.