Installing on Windows

EasyHybrid was developed for Linux and relies on technologies such as GTK3, Cython, and OpenGL. It does not run natively on Windows. The recommended approach for Windows users is to run EasyHybrid through WSL2 (Windows Subsystem for Linux 2), which provides a complete Linux environment within Windows while allowing Linux graphical applications to run through WSLg, the integrated graphical support for WSL.

WSL2 with WSLg is required for the EasyHybrid GTK3+OpenGL graphical interface to open; WSL1 does not provide the necessary graphical support.

This tutorial guides you through the entire process, from setting up WSL2 and Ubuntu on a clean Windows installation to installing and launching EasyHybrid.

Alternative: you can also use a virtual machine running Ubuntu (VirtualBox, VMware). The process inside the VM is identical to Step 3 onward in this tutorial, but WSL is lighter and faster to set up.

Prerequisites:

• Windows 10 (version 2004 or later, build 19041+) or Windows 11

• An internet connection

• About 5 GB of free disk space

• Administrator permissions on Windows

Step 1 — Install WSL and Ubuntu

1. 1. Open PowerShell as Administrator (right-click the Start menu → "Windows PowerShell (Admin)" or "Terminal (Admin)").

   2. Run:

wsl --install

1. 3. Restart your computer when prompted.

   4. After restarting, Ubuntu should open automatically and ask you to create a username and password for Linux (this can be different from your Windows login). Write this password down — you'll need it every time you use sudo.

Step 2 — Update WSL and enable graphics (WSLg)

This step is what makes the EasyHybrid window able to display. Back in PowerShell (Administrator), run:

wsl --update

This updates the WSL kernel and WSLg, the component that lets Linux graphical applications appear on your Windows desktop. On current Windows 10/11 this is included by default, but running wsl --update guarantees you have the latest version. Then make sure WSL2 is the default for any future distributions:

wsl --set-default-version 2

Step 3 — Confirm you are on WSL2 (not WSL1)

Still in PowerShell, run:

wsl --list --verbose

Look at the VERSION column. It must show 2 for your Ubuntu distribution:

  NAME     STATE     VERSION 

* Ubuntu   Running   2

If it shows 1, convert it to WSL2:

wsl --set-version Ubuntu 2

(Replace Ubuntu with the exact name shown in the list if different.) The conversion can take a few minutes.

Step 4 — Update Ubuntu

1. 1. Inside the Ubuntu terminal (open it from the Start menu by typing Ubuntu), run:

sudo apt update && sudo apt upgrade -y

Step 5 — Verify the graphical support works

EasyHybrid needs a working graphical display. Test it with a small GUI program before installing EasyHybrid itself. In the Ubuntu terminal:

sudo apt install -y x11-apps

xcalc

If a small calculator window appears on your Windows desktop, WSLg is working and EasyHybrid's window will be able to display. Close the calculator and continue. (You can remove the test program later with sudo apt remove x11-apps.)

Step 6 — Install system dependencies

1. 1. EasyHybrid needs Python 3, Cython, GTK3, and OpenGL libraries. Install everything at once:

sudo apt install -y \

  git \

  python3 \

  python3-pip \

  python3-dev \

  cython3 \

  build-essential \

  libgtk-3-dev \

  libgl1-mesa-dev \

  libglu1-mesa-dev \

  pkg-config \

  gir1.2-gtk-3.0 \

  python3-gi \

  python3-gi-cairo

If a package isn't found, run sudo apt update again and check that your Ubuntu version is recent (recommended: Ubuntu 22.04 or 24.04).

From this point on, the installation process is the same as on Linux. If you encounter any problems, please contact us at easyhybrid3@gmail.com

Step 7 — Important: where to keep your files

Keep the EasyHybrid checkout and the structures/trajectories you work with inside the Linux filesystem (under your Linux home, ~/ or /home/<username>/), not under the Windows drive at /mnt/c/....

Reading and writing project files through the /mnt/c/... Windows bridge is much slower than the native Linux filesystem, and for trajectory-heavy work the difference is very noticeable. Your Linux home is the fast path.

You can still reach your Windows files when you need to (they are under /mnt/c/Users/<YourWindowsName>/), but don't run EasyHybrid's working data from there.