Running GUI Code / Applications in GitHub Codespaces (on Windows)

Introduction: A somewhat rambling post outlining the steps to get GUI code / applications running in GitHub Codespaces on Windows. I went down a lot of wrong paths on this and my writing is a bit fragmented. Maybe I’ll clean it up sometime but wanted to share in case anyone else runs into similar issues.

I love Codespaces and they’re free (for public repositories). They work pretty seamlessly when one is building web applications, but what about when you need to create an application with a traditional GUI? Things aren’t quite as intuitive. You’ll likely get lots of messages from X11 complaining that it can’t open the display. Fear not, I’ve wandered through this wilderness before and hopefully can help you make it a little further than before.

I’m going to assume you already know how to create a GitHub Codespace, if not check out GitHub’s Codespace documentation.

You should also download, install, and run the GitHub CLI.

Microsoft Windows doesn’t have a built-in XWindows Server so you’ll need to download and install one of these as well. VcXsrv is popular and free. I’m using X410 (because I picked up a license cheap a few years back).

You’ll need to set the X11 forwarding on your Windows client. This can be done from the command prompt like so: setx DISPLAY "

You can connect to the Codespace using the command: gh cs ssh -- -XY. You’ll need to select the desired Codespace and you should be dropped into the shell.

Check that the DISPLAY environment variable is set: echo $DISPLAY. If it isn’t you’ll want to set it export DISPLAY=localhost:10.0.

You can attempt running your code/application now. If it doesn’t work try troubleshooting by using xeyes. You may need to install it in the Codespace: apt install x11-apps. Once this is done you can run it by entering xeyes at the terminal.


My initial goal was to load my GitHub Codespace in Visual Studio Code and run my application from within VSC. That didn’t work. This seems to be because VSC isn’t passing the -XY arguments when connecting to the Codespace. I’ll keep working on this, but for the moment I can do what I need to as is.


Built Upon

Thanks to those who went before me and made my life a little easier.

Leave a Reply