Uninstall Polaris, or start over

Two reasons bring people here: you are done with Polaris, or you want a clean slate before installing it again. The steps are the same. The last one decides which of the two you get.

The package manager removes what the package installed. It does not remove what Polaris created while running, what host setup wrote outside the package, or what you added yourself. This page lists all of it, in the order that works.

Before you start

1. Finish your games and end every stream from the client.
2. If you want a Space’s games and saves gone too, remove that Space for good now, while Polaris still runs: Remove Space, then Remove for good, on the Spaces page, as Rename, remove and restore describes. The last Space can only be archived there; section 1 below covers removing its home with Docker.
3. Quit Polaris. If it runs as a service:

   systemctl --user disable --now polaris

   If you start it from the desktop or the tray, quit it from the tray icon.
4. Check that nothing is left running:

   pgrep -a polaris

   It should print nothing. A second instance you forgot about, for example a validation build, counts too.

1. The Spaces security setup, which removal now handles

Since 1.4.13 you do not have to remember this. Removing the package runs the helper for you, before the helper itself goes away, and prints what it did. The helper is a package file and nothing else knows how to remove the policies it installed, so that moment is the only one that works.

Read the removal output. If it says the helper refused, the policies are still installed and the package is gone, so put it back, run the helper, then remove again:

sudo -H /usr/bin/polaris-spaces-setup remove

It removes only the SELinux policies and the input rule it installed, and it never touches player homes. If it refuses, Prepare Spaces security support explains each message.

On an older Polaris, or to check before removing, run that command yourself first. Doing it twice is harmless.

Docker keeps the gaming runtime image and each Space’s Steam home after the package is gone. Polaris deletes a home only when you remove its Space for good. The homes left are Docker volumes with opaque names, listed by docker volume ls next to your other volumes. Leave them if you might come back; the games and saves live there. Remove one with docker volume rm only when you are sure which Space it belongs to and want its games and saves gone for good. The runtime image is safe to remove at any time:

docker image ls 'ghcr.io/papi-ux/polaris-worker-steam'

Hosts without Spaces skip this section.

2. Turn off boot start, if you enabled it

Also before the package goes, because it needs the binary:

sudo -H polaris --setup-host --disable-headless-boot

If the package is already gone, remove the boot hook by hand instead:

rm -f ~/.config/systemd/user/default.target.wants/polaris.service

Lingering stays on because other services may rely on it. Turn it off yourself if nothing else needs your session at boot:

loginctl disable-linger "$USER"

3. Remove the package

Fedora:

sudo dnf remove polaris

Ubuntu:

sudo apt remove polaris

Arch Linux:

sudo pacman -R polaris

SteamOS:

sudo steamos-readonly disable
sudo pacman -Rns polaris
sudo steamos-readonly enable

Bazzite:

sudo rpm-ostree uninstall polaris

Then reboot into the new deployment.

The package takes its binaries with it, including polaris-spaces-setup, plus the user service unit, the udev rules and modules-load configuration under /usr/lib, the desktop entries, the polkit policy the Spaces page asks for administrator approval with (/usr/share/polkit-1/actions/dev.polaris-stream.app.Polaris.policy) and /usr/share/polaris. The uinput and uhid kernel modules stay loaded until the next reboot, which is harmless.

If this host captures through DRM/KMS it also has the polaris-kms package, which carries the privileged capture helper. Remove it the same way and in the same command, or it is left depending on a Polaris that is no longer there. Run sudo -H polaris --setup-host --disable-kms first, while Polaris is still installed: that points the user service back at the packaged binary before the helper it names goes away, and a service pointed at a binary that no longer exists cannot start at all (systemd reports status=203/EXEC).

4. What the package does not take with it

Check each of these. On a host that only ever ran the packaged Polaris, most of them are absent.

• Rules copied into /etc. Older host setups copied the udev rules and modules-load configuration into /etc. The package manager does not know about those copies.

  sudo rm -f /etc/udev/rules.d/60-polaris.rules /etc/modules-load.d/60-polaris.conf
  sudo udevadm control --reload-rules

• /usr/share/polaris still present. The package manager leaves the folder when something else wrote into it, for example web assets deployed from a source build or an .rpmsave file. Once the package is gone, remove it:

  sudo rm -rf /usr/share/polaris

• The Spaces security state. The helper keeps a small record under /var/lib/polaris. Remove it after step 1:

  sudo rm -rf /var/lib/polaris

• Docker group membership. Give Polaris access to Docker, or the same terminal step, added the account Polaris runs as to the docker group, and the package does not take it back. If that account no longer needs Docker without sudo:

  sudo gpasswd -d "$USER" docker

• KWin screencast permissions, on KDE hosts. Polaris registers itself for KWin’s screencast permission by writing ~/.local/share/applications/dev.polaris-stream.app.Polaris.kwin.<id>.desktop, one per binary path, and never removes them, so they pile up across upgrades. Remove them:

  rm -f ~/.local/share/applications/dev.polaris-stream.app.Polaris.kwin.*.desktop

• Installs from source. If you ever installed a source build, its files live under /usr/local and no package manager knows them: /usr/local/bin/polaris*, /usr/local/share/applications/dev.polaris-stream.app.Polaris*.desktop (this is what keeps “Polaris” in the application launcher after the package is gone), /usr/local/share/polaris, /usr/local/lib/systemd/user/polaris.service, and the icons under /usr/local/share/icons/hicolor/scalable/apps/polaris.svg and /usr/local/share/icons/hicolor/scalable/status/polaris-*.svg. Because /usr/local/share comes before /usr/share in XDG_DATA_DIRS, stale icons there shadow the packaged ones, so the panel and the launcher keep showing an old Polaris icon even after a reinstall. Remove all of it, then on KDE run kbuildsycoca6 --noincremental so the launcher forgets the entry, and restart the panel or log out and in:

  sudo rm -rf /usr/local/bin/polaris* /usr/local/share/applications/dev.polaris-stream.app.Polaris*.desktop \
    /usr/local/share/polaris /usr/local/lib/systemd/user/polaris.service \
    /usr/local/share/icons/hicolor/scalable/apps/polaris.svg \
    /usr/local/share/icons/hicolor/scalable/status/polaris-*.svg
  kbuildsycoca6 --noincremental
  systemctl --user restart plasma-plasmashell.service

• Your own additions. Unit overrides under ~/.config/systemd/user/, udev rules you wrote for a virtual display, firewall openings for the Polaris ports, or an extra binary you copied into /usr/bin while testing. Only you know about these; ls /usr/bin/polaris* and ls /etc/udev/rules.d/ | grep polaris find the common ones.
• Steam Input. If you applied the Doctor fix that turns off Steam’s Xbox configuration support, Steam keeps that setting after Polaris is gone. Turn it back on in Steam under Settings, Controller, if you want it; Steam Input and virtual controllers explains what it does.
• An older host’s KMS copy. Polaris releases before 1.4.13 had you copy the binary to /usr/local/bin/polaris-kms by hand for DRM/KMS capture. sudo -H polaris --setup-host --disable-kms removes that copy, its unit drop-in and the capability together, before you remove the package. The Bazzite guide also shows the steps by hand.
• The polaris-kms group. Removing the package leaves the group behind, with whoever was added to it still a member. It grants nothing once the helper is gone, so it is harmless to keep, and sudo groupdel polaris-kms removes it if you would rather it were not there.

5. Your data

Everything Polaris created while running lives in one folder, ~/.config/polaris:

Files	What they hold	Keep them if
polaris.conf	host settings: capture, modes, HDR, ports	you want the same setup back
polaris_state.json, credentials/	the web UI account and every paired device	you do not want to pair every device again
apps.json, library_sources.json	the library and its ROM folders	you want the library back
device_db.json, client_profiles.json	per-device tuning	you tuned devices by hand
covers/, artwork/	downloaded box art	never needed; they come back
polaris.log*	logs	you plan to report a problem

Back the folder up before deciding. It is small:

tar czf ~/polaris-config-$(date +%F).tgz -C ~ .config/polaris

To keep Polaris off the machine for good, or to install it again as if for the first time:

rm -rf ~/.config/polaris

To install again and keep your account, devices and library, leave the folder alone. The next install finds it and shows the login page instead of the welcome page.

6. Check

pgrep -a polaris
ls -d /usr/bin/polaris* /usr/share/polaris /etc/udev/rules.d/*polaris* \
  /etc/modules-load.d/*polaris* /var/lib/polaris ~/.config/polaris 2>/dev/null
ls -d /usr/local/bin/polaris* /usr/local/share/applications/dev.polaris* \
  /usr/local/share/icons/hicolor/*/*/polaris* ~/.local/share/applications/dev.polaris* 2>/dev/null
systemctl --user status polaris

Everything but the last line prints nothing, and the last says the unit could not be found. Anything that still shows up belongs to one of the sections above.

7. Install again

Follow the quickstart or your distribution’s page. Two things to know:

• With ~/.config/polaris gone, the console opens on the welcome page and asks for a new account. With the folder kept, it opens on the login page and your devices are still paired. Web UI credentials covers both.
• DRM/KMS capture needs the polaris-kms package installed alongside Polaris, and then one command:

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

  Log out and back in afterwards the first time, because a session picks up its groups at login. After that it stays working: the capability belongs to the package, so an upgrade no longer takes it away and there is nothing to re-run.