Table of Contents
- Why Zed on WSL2?
- Prerequisites
- Step 1 – Update WSL and Ubuntu
- Step 2 – Install Required Packages
- Step 3 – Install Zed
- Step 4 – Configure WSL Environment
- Step 5 – Launch Zed
- Troubleshooting & Common Issues
- Notes and Limitations
- Additional Resources
Why Zed on WSL2?
I found Zed while looking for a light weight code editor with AI features. Zed feels like it is built for the programmer, with its simple, craftmanship quality, and obsession to every pixel. The problem? It is officially supported just on MacOS and Linux, while I have a Windows machine.
Thankfully, with WSL2 (Windows Subsystem for Linux) you can install it on Windows. By installing Zed inside Ubuntu on WSL2, you can be on Windows and you wouldn't need to buy a Mac. The only downside? Getting Zed to cooperate with WSL2 can be a fit annoying especially around GPUs and display protocols.
In this guide, I’ll show you every trick I’ve learned, from solving “Unsupported GPU” errors to making those blank editor windows disappear. Let’s get Zed running smoothly so you can code like a boss on your Windows machine.
Prerequisites
- Windows 10 or 11 with WSL2 installed
- Ubuntu 22.04 (or newer) running on WSL2
- Administrator access to PowerShell
- Basic familiarity with command-line operations
Quick Tip: Don’t have WSL2 yet? Check the official docs here to install and configure it before diving into Zed.
Step 1 – Update WSL and Ubuntu
Let’s get everything up-to-date so we don’t run into random dependency issues.
PowerShell (Run as Admin)
wsl --update
Inside Ubuntu (WSL)
sudo apt update
sudo apt upgrade
Why This Matters:
- Ensures you have the latest WSL2 version with crucial security patches.
- Keeps your Ubuntu packages up-to-date (so nothing breaks halfway through).
Step 2 – Install Required Packages
Next, we need a couple of things to make sure Zed (which relies on GPU acceleration) plays nice on WSL2.
Install Vulkan & Mesa Drivers
# Vulkan dev libraries
sudo apt-get install libvulkan-dev
# Add Mesa repository for better GPU drivers
sudo add-apt-repository ppa:kisak/kisak-mesa
sudo apt update
sudo apt upgrade
Why This Matters:
-
Vulkan (libvulkan-dev):
- Required for GPU rendering in Zed.
- Provides the Vulkan development files and a stable interface to your graphics system.
-
Mesa Repository (kisak/mesa):
- Newer, open-source drivers that improve performance in WSL2.
- Minimizes weird rendering glitches in GPU-heavy apps like Zed.
Step 3 – Install Zed
Now for the main event! Let’s pull down Zed via the official installation script.
One-Liner Installation
curl -f https://zed.dev/install.sh | sh
Why This Matters:
- Grabs the latest official Zed build.
- Sets up required components and permissions automatically.
- You’re ready to rock in minutes without messing around with manual packages.
Step 4 – Configure WSL Environment
Here’s where we wrestle with display protocols and GPU emulation. We need to tell Zed that:
- It’s allowed to use a software (emulated) GPU if hardware access isn’t fully available.
- It should switch to X11 if Wayland is causing problems.
Find Your Shell
Inside Ubuntu:
echo $SHELL
- If you see /bin/bash, you’re on Bash.
- If you see /bin/zsh, you’re on Zsh.
For Bash Users
Add these lines to your ~/.bashrc:
echo 'export ZED_ALLOW_EMULATED_GPU=1' >> ~/.bashrc
echo 'alias zed="WAYLAND_DISPLAY='' zed"' >> ~/.bashrc
source ~/.bashrc
For Zsh Users
Add these lines to your ~/.zshrc:
echo 'export ZED_ALLOW_EMULATED_GPU=1' >> ~/.zshrc
echo 'alias zed="WAYLAND_DISPLAY='' zed"' >> ~/.zshrc
source ~/.zshrc
Just Want to Test Without Editing .rc Files?
WAYLAND_DISPLAY='' zed --foreground
Why This Matters:
-
ZED_ALLOW_EMULATED_GPU=1: Lets Zed run even if your GPU is only partly accessible (common in WSL2).- Allows Zed to run with software GPU emulation (llvmpipe)
- Overrides default behavior of refusing to run with emulated GPUs
- Essential for WSL2 environments where hardware GPU access might be limited
-
WAYLAND_DISPLAY='': Forces Zed to use X11, preventing those pesky “UnsupportedVersion” or blank screen issues.- Forces Zed to use X11 instead of Wayland
- Prevents "UnsupportedVersion" errors
- Resolves display protocol compatibility issues in WSL
Step 5 – Launch Zed
Finally, fire it up:
zed
If everything went well, you should see the Zed editor window pop up. Time to code!
Troubleshooting & Common Issues
1. Empty Window or Just an Outline
- Make sure libvulkan-dev is installed.
- Confirm your Mesa drivers are at least 24.1 or newer.
- Double-check
WAYLAND_DISPLAY=''is in your alias or environment. - Try
zed --foregroundto see if that resolves the display glitch.
2. “Unsupported GPU” Warning
This often shows up in WSL2. Here’s the fix:
# For Bash:
echo 'export ZED_ALLOW_EMULATED_GPU=1' >> ~/.bashrc
source ~/.bashrc
# For Zsh:
echo 'export ZED_ALLOW_EMULATED_GPU=1' >> ~/.zshrc
source ~/.zshrc
Performance Tip: If you have both an integrated and a discrete GPU (like Intel + NVIDIA), you can use
vulkaninfo --summaryto see your GPU list and ensure you’re using the better one.
3. Graphics Performance Concerns
- Keep your Windows GPU drivers updated from the official vendor site.
- Understand that WSL2’s GPU pass-through might not be as fast as native Linux.
Notes and Limitations
- This is still a workaround. Zed has promised a native Windows client, so treat this as a temporary solution.
- Expect some overhead with GPU emulation under WSL2.
- Stay on top of Windows updates, WSL2 updates, and Mesa drivers to keep everything running smoothly.
Additional Resources
Got more questions?
- Leave a comment below, or hit me up on LinkedIn. I’d love to hear how this worked for you—or help you debug if things went sideways!
Meta Description (for SEO):
Learn how to install and run the Zed code editor on Windows 10 or 11 using Ubuntu WSL2. This detailed guide covers prerequisites, Vulkan setup, GPU fixes, and troubleshooting for “Unsupported GPU” warnings.
Top comments (1)
thank you, i can run without any GPU hassle.. but I can't sign in, it says authentication canceled. well at least i can use zed