Install on Ubuntu 24.04

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

Fresh install: open https://localhost:47990/#/welcome, create the web UI account, and pair Moonlight, Nova, or another GameStream-compatible client.

Upgrade or reinstall: open https://localhost:47990/#/login and use the existing account. APT package operations preserve credentials, pairing keys, settings, and the library under ~/.config/polaris; removing the DEB does not reset the web account. If needed, follow the credential reset instead of returning to Welcome.

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 libei-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 \
  glslang-tools libvulkan-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.

After the restart, return to https://localhost:47990/#/login with the existing web credentials.

Uninstall

systemctl --user disable --now polaris
sudo apt remove polaris

Package-owned udev rules and modules-load configuration are removed with the package. Host configuration in ~/.config/polaris is left in place.

For a clean slate, or to remove what the package leaves behind, see Uninstall Polaris, or start over.

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. The experimental Vulkan Video encoder does require this KMS setup and an explicit capture = kms selection.

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.