Auto-starting photo slideshow for Ubuntu Server — minimal X11, no desktop required.
Turn any PC, Intel Compute Stick, or Raspberry Pi running Ubuntu Server into a dedicated photo display. One install script, boots straight into the slideshow, zero interaction needed.
- One-script install — everything configured in a single run
- Auto-detects GPU — Intel, AMD, NVIDIA, QXL (QEMU/KVM), VMware, VirtIO
- Boots straight into slideshow — auto-login + auto-start X, no keyboard needed
- Subfolder support — recursively scans your photos directory at any depth
- Hot-reload — drop new photos in the folder, they appear on the next cycle, no restart needed
- Smooth crossfade transitions with preloading
- Shuffle or sequential playback (configurable)
- Clock overlay — subtle time display in the corner
- Screen blanking disabled — display stays on permanently
- Ubuntu Server 22.04 LTS or 24.04 LTS (minimal install)
- A user account with
sudoaccess - Internet connection (for package installation)
Works on bare metal and virtual machines (QEMU/KVM, VMware, VirtualBox, Proxmox).
# 1. Download the install script
wget https://raw.githubusercontent.com/jermsmit/slideshow-kiosk/main/install-slideshow.sh
# 2. Run it (as your normal user, NOT root)
chmod +x install-slideshow.sh
./install-slideshow.sh
# 3. Add your photos
cp /path/to/your/photos/* ~/photos/
# 4. Reboot
sudo rebootThe display will boot directly into the slideshow.
The system has two components that start automatically on boot:
Boot
└─ systemd → slideshow.service (Python HTTP server, port 8765)
└─ getty → auto-login → startx
└─ .xinitrc → openbox + Chromium (kiosk mode)
└─ http://127.0.0.1:8765
slideshow_server.py— lightweight Python HTTP server that scans~/photosand serves imagesslideshow.html— fullscreen browser slideshow with crossfade transitions- Chromium runs in
--kioskmode (fullscreen, no UI, no cursor) - Openbox provides just enough window management to host the browser
Edit ~/slideshow/slideshow.html and adjust the config block at the top of the script:
const INTERVAL_MS = 8000; // time per slide in milliseconds
const SHUFFLE = true; // false = alphabetical order
const PRELOAD_AHEAD = 2; // images to preload in advanceTo change the photos directory, edit ~/slideshow/slideshow_server.py:
PHOTO_DIR = str(Path.home() / "photos") # change this pathJPG JPEG PNG GIF WEBP BMP
Subfolders are supported — the server recursively scans the entire photos directory tree and flattens all images into a single slideshow pool.
# Watch server logs live
sudo journalctl -u slideshow -f
# Restart the photo server
sudo systemctl restart slideshow
# Test the server from command line
curl http://127.0.0.1:8765/photos
# View Xorg errors
cat ~/.local/share/xorg/Xorg.0.logThe installer auto-detects your VM GPU and applies the correct configuration. For best results:
| Hypervisor | Recommended display settings |
|---|---|
| Proxmox | Display: VirtIO-GPU or VMware compatible |
| virt-manager / QEMU | Video: QXL with SPICE, or VGA with VNC |
| VirtualBox | Graphics Controller: VMSVGA or VBoxVGA |
| VMware | Default SVGA adapter works out of the box |
If using QXL, the installer adds the required video=qxl:1024x768 kernel boot parameter automatically to ensure /dev/fb0 is available at startup.
| Hardware | Status |
|---|---|
| Intel / AMD bare metal | ✅ |
| Raspberry Pi 4 / 5 | ✅ |
| QEMU/KVM — QXL GPU | ✅ |
| QEMU/KVM — VGA GPU | ✅ |
| VMware Workstation / ESXi | ✅ |
| Intel Compute Stick | ✅ |
slideshow-kiosk/
├── install-slideshow.sh # Single installer — run this
└── README.md
The installer writes the following to the target machine:
~/slideshow/
├── slideshow_server.py # Python HTTP server
├── slideshow.html # Slideshow frontend
└── start-kiosk.sh # X11 session launcher
~/photos/ # Put your photos here
MIT — free to use, modify, and distribute.
Issues and pull requests welcome. If you get this running on new hardware or a hypervisor not listed above, please open an issue to let us know!