Installation

Installation

Requirements

Requirement	Details
OS	Pop!_OS 22.04 or any Debian / Ubuntu ≥ 20.04
Display server	X11 or Wayland (auto-detected at runtime)
Python	3.9 or later
Phone	Any browser on the same network — iOS Safari, Android Chrome, etc.

The following packages are installed automatically as dependencies:

python3-gi  python3-gi-cairo  gir1.2-gtk-3.0  xdotool

Optional but recommended (Wayland text input and brightness control):

wtype  brightnessctl

---

Option A — Install the pre-built .deb

This is the recommended path. You build on your Mac/PC and copy to the HTPC.

1. Download or build the package

Grab the latest .deb from the Releases page, or build it yourself — see Building from Source.

2. Copy to the HTPC

scp htpc-remote_1.0.2_all.deb darren@192.168.1.x:/home/darren/

3. Install on the HTPC

sudo apt install ./htpc-remote_1.0.2_all.deb

The installer (postinst) does five things automatically:

1. Creates /opt/htpc-remote/venv — a Python virtualenv with all pip dependencies
2. Installs FastAPI, uvicorn, pynput, evdev, qrcode into the venv
3. Writes a udev rule so the Wayland backend can write to /dev/uinput
4. Runs systemctl --user --global enable htpc-remote — enables the service for all users
5. Starts the service immediately for the currently logged-in session

4. Log out and back in

The QR popup will appear within a few seconds of logging in. You only need to do this once — from now on it starts automatically.

---

Option B — Install from source (no Docker)

If you prefer to skip packaging entirely:

git clone https://github.com/dnaidoo621/htpc-remote
cd htpc-remote

# Create venv and install deps
python3 -m venv venv --system-site-packages
source venv/bin/activate
pip install fastapi uvicorn pynput evdev qrcode[pil] pillow

# Run directly
python run.py

This skips the systemd service — you'd need to wire that up manually if you want auto-start.

---

Uninstalling

sudo apt remove htpc-remote

The prerm script stops and disables the service before removal. Your venv at /opt/htpc-remote/ is also cleaned up.

---

Upgrading

Same as installing — just run sudo apt install ./htpc-remote_<new-version>_all.deb. The postinst script handles the venv update and service restart.

Tip: Always restart the service after upgrading even if the installer does it — systemctl --user restart htpc-remote — to be sure the new code is running.