Installing GitButler on Windows via WSL

GitButler-WSL.md

Installing GitButler on WSL Ubuntu - A Complete Guide

Last updated: 2025-09-11 Installing Gitbutler Version: 0.16.0

This guide will provide a complete walkthrough for getting GitButler setup and functioning on a windows environment using Windows Subsystem for Linux (WSL).

Please note that GitButler on windows via wsl is not well tested and not officially supported. Also, please note that installing and running GitButler on windows and pointing it to a WSL project folder or visa versa is not currently supported.

Prerequisites:

• You must be running Windows 10 version 2004 and higher (Build 19041 and higher) or Windows 11 for this guide to work correctly.

Known Issues

WSL Installation - Ubuntu 24

To start we must use the wsl command in windows to set up our linux environment in windows. If you already have a WSL instance up and running, you can skip ahead to the GitButler Install portion of this guide. A current known list of linux distributions that work with gitbutler can be found in the following Gitbutler Github Issue

The most common linux distro and the default provided by WSL is Ubuntu. As of the current version of this guide, Ubuntu 24.04 is the default distro used by WSL and will be what I am using for the guide. I hope to do some testing with other WSL distros later.

To start, you will need to open a powershell window as administrator and run the following command:

wsl --install

Once this has completed, you should restart your computer.

After your computer is restarted you can open the Ubuntu progam that is now listed in your start menu, or open a new Ubuntu terminal using the windows terminal program.

In the Ubuntu terminal you should now run:

$ sudo apt update && sudo apt -y upgrade

This will get your system fully up to date, and now we can move on to installing GitButler!

GitButler Install

Before we can install GitButler we need to install the WSL Utilities package which will provide better integration between windows and the WSL instance, and will allow gitbutler to open the user login link in your current browser in windows.

$ sudo apt install -y wslu

While those are installing, go to https://gitbutler.com and download either the Linux Deb or Linux AppImage version of GitButler.

AppImage vs Deb

There are a few pros/cons to each. If you use the deb you will need to manually update any time there is a new GitButler version by downloading the new deb and running the below install process for each new version. The AppImage on the other hand will prompt you when there are updates and can be quickly and easily updated, however there is more initial setup required to add a desktop shortcut on windows that will properly launch the AppImage version.

Deb Install Instructions

Once you have the Linux Deb version downloaded, open up windows file explorer, and in the document url bar near the top type in \\wsl.localhost\Ubuntu\home\ and then press enter. Then select the folder with your Ubuntu username. This is where we will want to place the .deb file we downloaded from the GitButler website so that we can access it inside our Ubuntu instance. Go ahead and do this now.

Lets go back to our Ubuntu instance and cd ~/ to make sure you are in your home directory. If you use the ls command you should be able to see the .deb file that you put there in the previous step. In my case the file is called GitButler_0.16.0_amd64.deb.

Now we are ready to start installing git butler. Run the following command (replacing the GitButler_0.16.0_amd64.deb file name with the name of the .deb file that you downloaded) to start the process:

$ sudo dpkg -i GitButler_0.16.0_amd64.deb

Once it is done running it will show that there were dependency errors. This is ok. To solve the dependency errors we need to run the following command:

$ sudo apt install -y -f

This will take a while as there are many dependency packages to install. Once the dependencies are installed, you can now open git butler for the first time using the following command.

$ gitbutler-tauri

Unfortunately there is not currently an easy way to update the application. Any time you would like to update GitButler you will need to manually download the .deb file from the website, and follow the above instructions to install the new version. If they end up with a more consistent way to get the download url for the most recent version, then a script might allow automatically updating GitButler, but until then, if you would like to be able to update GitButler from within the app, then you will need to use the AppImage version.

AppImage Install Instructions

Once you have the Linux AppImage version downloaded, open up windows file explorer and navigate to \\wsl.localhost\Ubuntu\home\. Then select the folder with your Ubuntu username. This is where we will want to place the .AppImage.tar.gz file we downloaded from the GitButler website so that we can access it inside our Ubuntu instance. Go ahead and do this now.

Lets go back to our Ubuntu instance and cd ~/ to make sure you are in your home directory. If you use the ls command you should be able to see the .AppImage.tar.gz file that you put there in the previous step. In my case the file is called GitButler_0.16.0_amd64.AppImage.tar.gz.

Next lets extract the .AppImage by running the following command (please replace the file name with the file you downloaded):

$ tar -xzf GitButler_0.16.0_amd64.AppImage.tar.gz

Before we can run the extracted AppImage we have to install a few extra packages that are required to make it run:

$ sudo apt install -y fuse libopengl0 gnome-keyring seahorse

Once those have been installed, we will need to set up seahorse which stores passwords and application secrets. The AppImage version of Gitbutler requires this to be set up or else you will get lots of password and application secret related errors.

To set this up, start by running seahorse from the terminal:

$ seahorse

This will open up the seahorse gui window. If you are on a fresh wsl install then it will likely say "This collection seems to be empty". If you have already set up some SSH keys or other application keys on this wsl instance, then it will likely open up showing those keys. Below are the steps to setup seahorse.

• At the top left of the window should be a button with a < symbol in it. Click that to go back to the main menu.
• At the top left should now be a button with a + symbol. Click that and select "Password Keyring".
• Give it the name Login
• Give it a password you can remember later
• Right click the "Login" folder that is now in the list under "Passwords" and select "Set as Default"
• Close the Seahorse Window

Now that Seahorse has been setup, you can run $ ./GitButler_0.16.0_amd64.AppImage to launch GitButler directly. However, if you do not want to launch it from the command line every time, we need to do some more setup.

From here the easiest way to get the AppImage setup to act like a normally installed app would be to use AppImageLauncher. However, for the sake of this tutorial I am going to provide instructions to integrate the AppImage manually so as to avoid requiring you to install possibly untrusted software.

First we need to rename the appimage to gitbutler-tauri because that is the application name used by the .desktop file later in the process:

$ mv GitButler_0.16.0_amd64.AppImage gitbutler-tauri

Next, lets symlink our app image to /usr/bin so that its in a location that ubuntu expects:

$ sudo ln -s ~/gitbutler-tauri /usr/bin/

If you are storing the git-butler AppImage somewhere else, make sure that you adjust the symlink target path to match where you have it stored.

Next we will need to extract the GitButler.desktop file from the AppImage along with the icon files and move the .desktop file to /usr/share/applications, and move the icon files to /usr/share/icons so that windows knows to add it to the list of applications installed on your Ubuntu WSL instance, and uses the correct icon.

First lets unwrap the AppImage by running:

$ gitbutler-tauri --appimage-extract

This will create a squashfs-root directory with the GitButler.desktop file and icon directory we will need inside. Lets start by copying over the icon files first before moving the desktop file so that windows picks up the icons correctly.

$ sudo cp -r squashfs-root/usr/share/icons /usr/share/

Next lets move the .desktop file to where it needs to go, and then remove the squashfs-root directory:

$ sudo cp squashfs-root/GitButler.desktop /usr/share/applications/
$ rm -rf squashfs-root/

And thats it! Git butler should now show up in the windows start menu app list under the Ubuntu folder.

If you encounter the following error when launching git-butler from command-line

git-butler: error while loading shared libraries: libharfbuzz.so.0: cannot open shared object file: No such file or directory

run the following command

sudo apt install libharfbuzz0b

@KroniK907, I appreciate your effort to write this guide. 💯 🥇

I really wanted to try out GitButler with my WSL dev environment and thanks to you I managed to do so. 🙇

I'm using version 0.11.7 and the login button does not work. GitButler initialized correctly, I have Firefox in Ubuntu installed alongside the other dependencies mentioned here. There are also no errors shown in the terminal during the AppImage execution, it just doesn't open the link. Where I do see errors is in the console within the Tauri app (View > Developer Tools): Failed to load resource: the server responded with a status of 401 (Unauthorized) https://app.gitbutler.com/api/login/user/5a872d7c214353e5a457db03359.json

EDIT:
using sudo git-butler fixes the link opening issue

sudo dpkg -i git-butler_0.10.7_amd64.deb
dpkg: error: cannot access archive 'git-butler_0.10.7_amd64.deb': No such file or directory

maybe the installer could be updated or provided with current dependencies. Or even as a snap. Seem to be endless missing dependency journey with wsl and ubuntu 24-04 (yes it's (too) recent )

Hello. Is it expected that I get a git-butler: command not found using the Deb Install Instructions?

Hello, I get git-butler: command not found as well with the Deb install method. The AppImage worked, some filenames are different now though.

so i've got this working generally following this guide, but I get the UI being very laggy, and on initial start it tends to hang for anywhere from 5-15 minutes before eventually becoming usable

does anyone else get that? found any workarounds?

A few updates I had to make for appimage install:

• Generally git-butler naming conventions seems to have been updated to GitButler; anywhere in these instructions that was git-butler I updated to use GitButler.
• renamed the exec line in the .desktop file to GitButler, which is the name of the link to AppImage file (was gitbutler-tauri in the extracted .desktop file)
• my WSL2 install was a bit out of date still running 22.04; the GitButler AppImage had libraries requiring glibc >= 2.38. I upgraded my wsl2 with:

   $ sudo apt update && sudo apt full-upgrade
   $ sudo do-release-upgrade

After this the desktop launcher worked from windows.