Here's how I set up a media PC using Kodi (formerly XMBC) and a Raspberry Pi 4. These instructions are for the bookworm version of Raspberry Pi OS.


The hardware is fairly straightforward, but here's what I ended up getting:

You'll probably want to add a remote control to that setup. I used an old Streamzap I had lying around.

Installing the OS on the SD-card

Plug the SD card into a computer using a USB adapter.

Download the imager and use it to install Raspberry Pi OS with desktop on the SDcard.

Then you can simply plug the SD card into the Pi and boot.

I created a new francois user account for myself.

System configuration

Using sudo raspi-config, I changed the following:

  • Set hostname (System Options)
  • Disable screen blanking (Display Options)
  • Enable ssh (Interface Options)
  • Configure locale, timezone and keyboard (Localisation Options)
  • Set WiFi country (Localisation Options)

Then I installed anacron to make sure that all cron jobs get run even when the machine is off:

apt install anacron

I found that automatic updates are already enabled by apt-daily-upgrade.timer.


In order to secure the Pi, I followed most of the steps I usually take when setting up a new Linux server.

Finally, I enabled the Uncomplicated Firewall. I had to reconfigure debconf to see all medium-priority questions:

dpkg-reconfigure debconf

before installing the ufw package:

apt install ufw

and only allowing ssh connections.

After starting ufw using systemctl start ufw.service, you can check that it's configured as expected using ufw status. It should display the following:

Status: active

To                         Action      From
--                         ------      ----
22/tcp                     ALLOW       Anywhere
22/tcp (v6)                ALLOW       Anywhere (v6)

Installing Kodi

Kodi is very straightforward to install since it's now part of the Raspbian repositories:

apt install kodi

To make it start at boot/login, while still being able to exit and use other apps if needed, I put the following at the end of ~/.config/wayfire.ini:

kodi=kodi -fs

and the following to prevent any form of sleep or screen locking:


In order to improve privacy while fetching metadata, I also installed Tor:

apt install tor
apt purge torsocks

and then set a proxy in the Kodi System | Internet access settings:

  • Proxy type: SOCKS5 with remote DNS resolving
  • Server: localhost
  • Port: 9050

Finally, to prevent Kodi from listening on UDP port 3702 on the local network:

--WARN-- [lin003w] The process `kodi.bin' is listening on socket 3702 (UDP on every interface) is run by francois.

Disable WS-Discovery from Services | SMB Client settings.

Network File System

In order to avoid having to have all media storage connected directly to the Pi via USB, I setup an NFS share over my local network.

First, give static IP allocations to the server and the Pi in your DHCP server, then add it to the /etc/hosts file on your NFS server:    pi

Install the NFS server package:

apt install nfs-kernel-server

Setup the directories to share in /etc/exports:

/pub/movies    pi(ro,insecure,all_squash,subtree_check)
/pub/tv_shows  pi(ro,insecure,all_squash,subtree_check)

Open the right ports on your firewall by putting this in /etc/network/iptables.up.rules:

-A INPUT -s -p udp -j ACCEPT
-A INPUT -s -p tcp --dport 111 -j ACCEPT
-A INPUT -s -p udp --dport 111 -j ACCEPT
-A INPUT -s -p udp --dport 123 -j ACCEPT
-A INPUT -s -p tcp --dport 600:1124 -j ACCEPT
-A INPUT -s -p udp --dport 600:1124 -j ACCEPT
-A INPUT -s -p tcp --dport 2049 -j ACCEPT
-A INPUT -s -p udp --dport 2049 -j ACCEPT

Finally, apply all of these changes:

systemctl restart nfs-kernel-server.service

On the Pi, put the server's static IP in /etc/hosts:    fileserver

and this in /etc/fstab:

fileserver:/data/movies  /kodi/movies  nfs  ro,bg,hard,noatime,async,nolock  0  0
fileserver:/data/tv      /kodi/tv      nfs  ro,bg,hard,noatime,async,nolock  0  0

Install the NFS client package:

apt install nfs-common

Then create the mount points and mount everything:

mkdir -p /kodi/movies
mkdir /kodi/tv
mount /kodi/movies
mount /kodi/tv


If you also want to play videos outside of Kodi, you may be interested in vlc. In that case, make sure you install these additional packages:

apt install vlc-plugin-pipewire pipewire-audio

and then set the default video output plugin to wayland and the default audio output plugin to pipewire.

I have found that sometimes no sound is coming out of vlc, but for some reason starting kodi and then shutting it down seems to reset pipewire.

Prevent frequent Wayland crashes back to the login screen

I was running into frequent problems whereby Kodi would be gone and replaced with what I initially thought was a lock screen. After looking into disabling any kind of power management or screensaver, I realized it wasn't actually a lock screen, but instead a login screen similar to the one reported here.

This suggested that something was causing Wayland to crash and restart back to the login screen (even though I have automatic login enabled). After running wlr-randr (not installed by default, but just an apt install wlr-randr away), I confirmed that my TV was connected to HDMI-A-1 and then appended the following to my /boot/cmdline.txt before rebooting:


This workaround is apparently useful in cases of unidentified HDMI hotplug-related bugs.