Skip to content

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.

Terminal window
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.

Terminal window
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.

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.

Terminal window
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.

Terminal window
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.

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

Terminal window
systemctl --user enable --now polaris

Only enable DRM/KMS capture if you specifically need it. It takes two steps, and the first one is a package: the capability lives in that package’s own metadata rather than on the Polaris binary, and --enable-kms refuses without it.

Terminal window
sudo apt install ./Polaris-kms-ubuntu24.04-x86_64.deb
sudo -H polaris --setup-host --enable-kms

Download Polaris-kms-ubuntu24.04-x86_64.deb from the same release as the Polaris .deb beside it: the two carry the same version, and the helper requires the exact version of polaris it was built with, so they have to be installed and updated as a pair. --disable-kms points the user service back at the ordinary binary.

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.

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:

Terminal window
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.

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

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.