Steam Deck Desktop Mode: How I Survived on SteamOS Upgrade

SteamOS Upgrade

How I Survived on SteamOS Upgrade

SteamOS is immutable Linux system witch will reset all packages in directory /usr during upgrade. Packages I needs is for web development and couldn't found in flatpak. For example, I need git command on every project I work. This package will being remove on every SteamOS upgrade. Then I wrote this to record how I survive on this ****.

Before doing anything, you should check below:

  • Check official FAQ, it helpful
  • Prepre a USB disk for recoveryFollow steps here
  • Search flatpak in "Discover" before doing anything on system. Can also search from web here

Got to do after every SteamOS upgrade

Initialize Pacman / Refresh Keys

  1. Disable read-only steam OS
sudo steamos-readonly disable
  1. Update PGP Keys
sudo pacman-key --init
sudo pacman-key --populate archlinux
echo "keyserver hkps://" | sudo tee /etc/pacman.d/gnupg/gpg.conf

Note: I'm not sure if we need keyserver from ubuntu.

  1. Upgrade System Keys
sudo pacman -Syy 
sudo pacman -Sy archlinux-keyring
sudo pacman-key --refresh-keys

Install Packages From Pacman

pacman will detect installed files (in etc) which the package may removed during SteamOS upgrade. You can install packages to see if any files needs to remove.
For my instance, this files needs to disappear before pacman install.

sudo mv /etc/libccid_Info.plist /etc/libccid_Info.plist.bak
sudo mv /etc/bind.keys /etc/bind.keys.bak

Install packages:

sudo pacman -S \
  yubikey-manager \
  git \
  python-pip \
  libfido2 \
  nginx \
  nginx-mod-auth-pam \
  nginx-mod-echo \
  nginx-mod-geoip2 \
  nginx-mod-modsecurity \
  ttf-fira-code \
  qt5-virtualkeyboard \
  bind-tools \
  gnome-keyring \
  libsecret \

# install fonts
sudo pacman -S \

Setup Systemctl Services

# yubikey (smart card service)
sudo systemctl enable pcscd.service
sudo systemctl start pcscd.service

# nginx
sudo systemctl start nginx
sudo systemctl enable nginx

Traditional Chinese IME

Install (New) Chewing input method for KDE ibus:

sudo pacman -S ibus-chewing


Magic touchpad gesture driver for linux. Check here for details.

git clone
cd libinput-gestures
sudo ./libinput-gestures-setup install

Re-Enable readonly on SteamOS

sudo steamos-readonly enable

Survived on SteamOS Update

Below is the things that automatically survived on SteamOS upgrade. I don't need to install again after upgrade.

Rootless Docker

You should check official document here first:

Change permission(list the document said)

sudo bash -c "echo 'deck:165536:65536' > /etc/subuid"
sudo bash -c "echo 'deck:100000:65536' > /etc/subgid"
curl -fsSL | sh
echo "export PATH=/home/deck/bin:$PATH" >> ~/.bashrc
echo "export DOCKER_HOST=unix:///run/user/1000/docker.sock" >> ~/.bashrc
systemctl --user start docker


curl -fsSL | sh

Test docker:

docker run --rm debian cat /etc/debian_version

Language / locaalization config

KDE Plasma

vim ~/.config/plasma-localerc




This will effect the flatpak install language

flatpak config --set languages 'zh;en'

Trouble shootings

1. GLIBC_2.3x not found

DO NOT UPGRADE GLIBC. If upgrade GLIBC, may break proton and game may not launch. eg.


Using Homebrew Linux


The installation process may take an hour during very large git repository.

/bin/bash -c "$(curl -fsSL"


brew update

Homebrew fomula - PHP


brew install php


brew upgrade php

Testing php cli

php --version

2. PGP keys is unknown trust when using pacman

When using pacman install packages, may have this error:

error: some-package: signature from "Some Person [email protected]" is unknown trust

SteamOS use it's own mirror for pacman. You can check /etc/pacman.d/mirrorlist for details. The problem is SteamOS not update frequently. PGP keys may expire before new SteamOS release.


  • Use "Init pacman / refresh keys" steps above may solve this issue.
  • Add newest mirror into pacman.

Add mirror to pacman

Search your list here
Use following command to add mirror to your own list.

echo "Server = https://your_own_mirrow/arch/\$repo/os/\$arch" | sudo tee /etc/pacman.d/non-steam-mirror

After that, editing main pacman.conf in etc, add your mirror file to list you want
vim /etc/pacman.conf

Include = /etc/pacman.d/non-steam-mirror
Include = /etc/pacman.d/mirrorlist

Notice The mirror may install latest version from community and break the dependency. You may want to remove list after refresh keys.
For example, install git from latest community version using pacman will have issue GLIBC_2.32 not found in SteamOS 3.3.2.

Refresh keys.

sudo pacman -Syy
sudo pacman -Sy archlinux-keyring
sudo pacman-key --refresh-keys

Remove non-steam-mirror in pacman.conf
vim /etc/pacman.conf

#Include = /etc/pacman.d/non-steam-mirror
Include = /etc/pacman.d/mirrorlist

3. Cannot Launch Virtualbox

Still struggle on this. :(

4. Install custom AUR

I thought I can't because here said:

  • /usr/include is simply missing on steam deck. meaning building programs on deck

Then I found here:

sudo pacman -S glibc
sudo pacman -S lib32-glibc
sudo pacman -S linux-headers
sudo pacman -S linux-api-headers

Install fakeroot ... etc

sudo pacman -S --needed base-devel

make something / makepkg something
oooooo:31:10: fatal error: stdio.h: No such file or directory

3. Bluetooth Microphone not Work

Due to steam disable HSP/HFP codec profile by default, you have to enable this profile manually.

Follow document here, you should be able select HSP on Bluetooth drop-down profile config.

Notice that, you don't have any interface to change bluetooth profile on Steam Deck gaming mode UI. You can only change this in decktop mode. Using microphone on bluetooth headset device will have lower quality audio output. You may want to change to A2DP by default.