Use GitKraken Desktop with Windows Subsystem for Linux (WSL 2)

Last updated: November 2026

Use this page to install and run GitKraken Desktop inside Windows Subsystem for Linux 2 (WSL 2) when your repositories live on the Linux file system.

Requirements and limits

• Windows requirement: Windows 11 or Windows 10 build 19044+
• Linux requirement: WSL 2 distribution with WSLg support
• GitKraken Desktop requirement: GitKraken Desktop 9.1.0+ for Linux
• Repository location rule: Keep repositories on the same file system as the GitKraken Desktop installation you use
• Cross-file-system warning: Opening WSL repositories from GitKraken Desktop on Windows, or Windows repositories from GitKraken Desktop in WSL, can cause degraded performance or broken features
• Coding agent note: In WSL, Windows-installed coding agent CLIs can take precedence over WSL-installed CLIs and prevent agent sessions from starting correctly
• Known issues: WSLg may have HiDPI scaling and window-snapping limitations

---

Quick Start

1. Update WSL 2: From PowerShell or Command Prompt (run as Administrator), run wsl --update. To install WSL with Ubuntu, run wsl --install -d ubuntu and reboot.
2. Download GitKraken Desktop for Linux: For Ubuntu, run:

   wget https://api.gitkraken.dev/releases/production/linux/x64/active/gitkraken-amd64.deb
   sudo apt install ./gitkraken-amd64.deb

3. Launch GitKraken Desktop: Run gitkraken in your WSL 2 terminal. With WSLg installed, the app displays natively within Windows.

Keep your repositories on the same file system as the GitKraken Desktop installation you use. Opening repositories across file systems (for example, opening a WSL repository from GitKraken Desktop installed on Windows) degrades performance or breaks features. When you do this, GitKraken Desktop prompts you to open the repository with the correct installation.

What WSL and WSL 2 are

Windows Subsystem for Linux (WSL) lets you run a Linux distribution and use Linux tools directly on Windows. WSL 2 runs an actual Linux kernel in a managed VM, which gives better performance and full system call compatibility.

To run Linux GUI apps, WSL 2 uses WSLg, which shows Linux apps on the Windows desktop. WSLg lets GitKraken Desktop for Linux run within WSL 2.

Microsoft recommends storing project files on the same operating system as the tools you’re using to avoid cross-OS performance issues.

How to use GitKraken Desktop with WSL 2

GitKraken Desktop works with repositories stored on your WSL 2 file system when installed and launched inside the WSL environment. With WSLg, GitKraken Desktop displays natively within Windows.

GitKraken Desktop notifies you when you open a repository from the other environment. For more information, see How cross-file-system access works in WSL 2.

How to set up GitKraken Desktop in WSL 2

To get started:

1. Update WSL 2: Make sure the latest version is installed with WSLg support.
2. Download GitKraken Desktop: Get the latest Linux version.
3. Install in WSL: Run the installer from your WSL 2 terminal.
4. Launch GitKraken Desktop: Run gitkraken in your WSL 2 terminal.

Most WSL distributions include Git by default. If needed, install or update Git for Linux.

---

WSL 2 and WSLg requirements

• Windows 11 or Windows 10 build 19044+
• WSL 2 distribution
• GitKraken Desktop version 9.1.0+ for Linux

---

How to install or update WSL 2 with WSLg support

GitKraken Desktop requires WSL 2 with WSLg support on Windows 11 or Windows 10 build 19044 or later.

To update WSL from PowerShell or Command Prompt (run as Administrator):

wsl --update

To install WSL with Ubuntu as the default distribution:

wsl --install -d ubuntu

After rebooting, complete the setup by creating a Linux username and password.

This installation includes WSLg.

---

How to download and install GitKraken Desktop on WSL 2

To install GitKraken Desktop within WSL, follow the Linux installation instructions.

For Ubuntu users:

wget https://api.gitkraken.dev/releases/production/linux/x64/active/gitkraken-amd64.deb
sudo apt install ./gitkraken-amd64.deb

If dependencies are missing, fix broken packages with:

sudo apt --fix-broken install

Then, launch GitKraken Desktop with:

gitkraken

If you installed the .tar.gz version, make sure gitkraken is in your PATH so this command works.

---

How WSL-specific GitKraken preferences work

In WSL, you can choose where GitKraken Desktop opens URLs and files. To configure these settings, go to Preferences > General.

By default:

• URLs open in your Windows default browser.
• GitKraken Desktop tries to open files on the WSL host distribution.

---

Known issues with WSL 2

GitKraken Desktop has these known limitations with WSLg:

• HiDPI displays may cause WSLg to inconsistently scale the UI.
• Window snapping might not function properly within WSLg.
• Windows-installed coding agent CLIs can take precedence over WSL-installed CLIs, which may cause coding agent sessions to fail to start as expected.

---

How to troubleshoot WSL 2 issues

If GitKraken Desktop opens with a black screen or other display issues, try these fixes:

• Reopen GitKraken Desktop as administrator.
• Update your graphics drivers.

If issues persist, you can disable GPU acceleration:

gitkraken --disable-gpu

To bypass certificate errors (for example, NET::ERR_CERT_AUTHORITY_INVALID), run:

gitkraken --ignore-certificate-errors

To fully restart WSL, run this command from PowerShell or Command Prompt as administrator:

wsl --shutdown

Then, reopen your Linux distribution or GitKraken Desktop.

How to sign in and connect integrations from WSL 2

When you sign in to your GitKraken account or connect an integration from GitKraken Desktop in WSL 2, the sign-in page opens in your Windows browser. GitKraken Desktop on Windows then completes the sign-in for GitKraken Desktop in your WSL distribution, so install GitKraken Desktop on Windows as well as in WSL.

If the hand-off fails, GitKraken Desktop on Windows shows one of these messages:

• Could not complete sign-in: GitKraken Desktop is not installed in WSL distro {name}. Install GitKraken Desktop in that distribution.
• Could not complete sign-in: failed to launch GitKraken Desktop in WSL distro {name}. Start GitKraken Desktop in WSL, then try again.
• Could not complete sign-in: invalid WSL distro name.

Each message ends with Sign in again from GitKraken Desktop in WSL. Start the sign-in again from GitKraken Desktop in WSL. If GitKraken Desktop is not installed on Windows, sign in with Manually enter authentication code in the Sign In to GitKraken window instead: paste the code from your browser and click Save.

---

How cross-file-system access works in WSL 2

GitKraken Desktop does not support opening repos stored on a different file system than the one where GitKraken Desktop is installed.

For the best experience:

• Install GitKraken Desktop on both Windows and WSL.
• Open each repository with the GitKraken Desktop installation on the same file system.

When you open a repository stored in WSL from GitKraken Desktop on Windows, or the reverse, GitKraken Desktop shows a prompt:

You can choose:

• Open Help Center: Opens this guide.
• Open with GitKraken in Ubuntu (your distribution’s name) or Open with GitKraken in Windows: Switches to the GitKraken Desktop installation on the same file system as the repository.
• Open Repository Anyway: Tries to open the repository, which may degrade performance or break features.
• Close: Cancels the action.