Linux Installation

Zeo is distributed as an AppImage. The AppImage is built on a Debian base and tested on modern glibc-based distributions: Ubuntu 22.04+, Fedora 38+, Debian 12+, Arch, and openSUSE Tumbleweed. Most other rolling and recent stable distros work without modification.

Download

Download the latest AppImage from the downloads page.

Installation Steps

  1. Download the AppImage.
  2. Make it executable: chmod +x Zeo-*.AppImage.
  3. Run it: ./Zeo-*.AppImage.

Desktop Integration

To integrate Zeo with your desktop environment:

# Extract the AppImage
./Zeo-*.AppImage --appimage-extract

# Move to /opt
sudo mv squashfs-root /opt/zeo

# Create a symlink
sudo ln -s /opt/zeo/AppRun /usr/local/bin/zeo

What's bundled vs. assumed

The AppImage bundles its own copy of KiCad, the agent, the terminal, Freerouting, Python 3.11, kipy, wxGTK 3.2.9, OCCT, ngspice, and glibc.

At launch the AppRun script compares the host's glibc to the bundled one. If the host is newer, it uses the host's dynamic linker so host GPU drivers and WebKit work natively. If the host is older, it falls back to the bundled glibc and linker.

The host system must provide:

  • glibc (any version; newer or older than bundled, both paths are supported)
  • GTK 3 runtime libraries (libgtk-3-0, fontconfig, gdk-pixbuf)
  • WebKit2GTK 4.1 (libwebkit2gtk-4.1) for the agent's webview panel
  • OpenGL / GPU drivers (Mesa or vendor drivers; Zeo uses host GPU drivers for the 3D viewer)
  • X11 or Wayland display server (with XWayland on Wayland)
  • FUSE for the AppImage mount step (or use --appimage-extract-and-run)

Unsupported or non-standard systems

If you're on a system that doesn't follow the FHS layout or doesn't ship the GTK3 / WebKit2GTK stack as standard packages (NixOS, GuixSD, Alpine with musl, etc.), the AppImage's library resolution will not work out of the box. Build from source instead. See Build from Source.

Troubleshooting

FUSE not available

If you see a FUSE error, extract and run directly:

./Zeo-*.AppImage --appimage-extract-and-run

WebKit panel is blank or fails to load

The agent panel uses libwebkit2gtk-4.1. If your distro only ships the older 4.0 series (some long-term-support releases), install the 4.1 variant:

  • Ubuntu/Debian: sudo apt install libwebkit2gtk-4.1-0
  • Fedora: sudo dnf install webkit2gtk4.1
  • Arch: sudo pacman -S webkit2gtk-4.1