Ubuntu Install Guide

Ubuntu 24.04 is the first Debian-family target for a direct Polaris DEB package. This path is extremely experimental and much more prone to breaking than the Fedora and Arch package paths while real-hardware validation is still limited. The CI path builds and smoke-tests Polaris-ubuntu24.04-x86_64.deb, and the asset is published with v1.0.3 and later Polaris releases.

[!WARNING] Treat the Ubuntu DEB as a tester package for now, not a stable recommended install. Ubuntu desktop environment differences, GPU driver packaging, compositor behavior, and Debian-family dependency drift can break this flow while support is still being validated.

Release Package

wget --output-document=./Polaris-ubuntu24.04-x86_64.deb https://github.com/papi-ux/polaris/releases/latest/download/Polaris-ubuntu24.04-x86_64.deb &&
sudo apt install ./Polaris-ubuntu24.04-x86_64.deb &&
sudo -H polaris --setup-host &&
polaris

Open https://localhost:47990, create the web UI password, and pair Moonlight, Nova, or another GameStream-compatible client.

Source Build Fallback

sudo apt-get update
sudo apt-get install -y \
  build-essential ccache cmake git ninja-build \
  libboost-all-dev libssl-dev libevdev-dev \
  libpulse-dev libopus-dev libcurl4-openssl-dev \
  libdrm-dev libgbm-dev libcap-dev libwayland-dev \
  libpipewire-0.3-dev libx11-dev libxrandr-dev \
  libxfixes-dev libxi-dev libxcb1-dev libxcb-shm0-dev libxcb-xfixes0-dev \
  libva-dev libminiupnpc-dev libnotify-dev nlohmann-json3-dev \
  libappindicator3-dev libgtk-3-dev \
  libavcodec-dev libavformat-dev libavutil-dev libswscale-dev \
  wayland-protocols grim labwc wlr-randr xwayland x11-utils nodejs npm

git clone --recursive https://github.com/papi-ux/polaris.git
cd polaris
npm ci --no-audit --fund=false
cmake -B build -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DPOLARIS_ENABLE_CUDA=OFF \
  -DCUDA_FAIL_ON_MISSING=OFF
cmake --build build -j"$(nproc)"
sudo cmake --install build
sudo -H polaris --setup-host
polaris

Use -DPOLARIS_ENABLE_CUDA=ON only when the CUDA toolkit is installed and you specifically want a CUDA-enabled local build.

Update

Download the newer .deb to the exact filename and repeat the failure-safe chain. Writing to the exact name matters: an existing file otherwise becomes Polaris-ubuntu24.04-x86_64.deb.1 while apt installs the stale original.

wget --output-document=./Polaris-ubuntu24.04-x86_64.deb https://github.com/papi-ux/polaris/releases/latest/download/Polaris-ubuntu24.04-x86_64.deb &&
sudo apt install ./Polaris-ubuntu24.04-x86_64.deb &&
sudo -H polaris --setup-host &&
systemctl --user restart polaris

--setup-host exits without asking for root when the package already provides the udev rules and modules-load configuration and the virtual input nodes are usable.

Optional Setup

Enable the user service if you want Polaris to start in the background:

systemctl --user enable --now polaris

Only enable DRM/KMS capture if you specifically need it:

sudo -H polaris --setup-host --enable-kms

The default compositor and portal paths do not require granting KMS capability.

Headless Labwc Checks

If a headless stream reports that video capture failed, confirm that the helper programs used by the private labwc runtime are installed and visible to Polaris:

command -v labwc wlr-randr Xwayland xdpyinfo
labwc --version

labwc: Required executable [labwc] was not found in PATH means the package or source install is missing the isolated compositor runtime. labwc: Exited before creating a Wayland socket means labwc started but failed before it could expose the stream-only Wayland socket; check the installed labwc/wlroots stack and retry from a normal Wayland desktop session first.

Validation Checklist

Please include these details when reporting Ubuntu issues:

Ubuntu version from lsb_release -a
package install or source build
GPU model and driver stack
desktop environment and display server, such as GNOME Wayland or KDE Wayland
whether sudo -H polaris --setup-host completed successfully
whether the web UI opens at https://localhost:47990
client used for pairing, such as Steam Deck Moonlight, Android Moonlight, or Nova
active capture path shown in the Polaris dashboard
whether headless mode and virtual display behavior worked after a reboot

Current Status

Ubuntu 24.04 builds and fast C++ tests run in CI. The DEB package is built, installed, checked for unresolved shared-library dependencies, and published on tagged builds. That CI coverage proves the package builds and installs, but the Ubuntu host runtime still needs broader real-hardware testing before this path is marked recommended.