Raspberry Pi Kiosk Mode: The Complete Guide

Raspberry Pi kiosk mode makes the Pi boot straight into one web page, full screen in Chromium, with no desktop, no taskbar and no mouse cursor, and it comes back by itself after a browser crash or a power cut. You can get there two ways: set it up by hand with the steps below, or let a one-command installer do the whole configuration for you, which is how TVpilot's Raspberry Pi player works.

This is the standard way to turn a cheap single-board computer and a spare TV into a dashboard, menu board, waiting-room display or lobby sign. The manual route is free, flexible and yours to maintain forever. The installer route handles the kiosk config, updates and remote content management for you. Choose manual if you have one or two screens that rarely change and you like owning the scripts; choose the installer if other people need to change content without touching the Pi.

Budget about an afternoon for the manual route, most of it spent testing reboots and network drops rather than typing commands.

What "kiosk mode" actually means on a Pi

On a Pi, kiosk mode means six things working together:

• Boot directly to a desktop session (or a minimal X/Wayland session) with no login prompt.
• Launch Chromium automatically, in full screen, pointed at a specific URL.
• Strip the browser chrome: no address bar, no tabs, no "restore session" popups.
• Hide the mouse cursor if nobody interacts with the screen.
• Recover automatically if the browser crashes, the network drops, or the power blips.
• Optionally, turn the TV itself on and off on a schedule.

The first four are the easy part of any Pi kiosk display. The last two (self-healing and TV power control) are where most DIY setups quietly fall short, because they only show up as problems after the Pi has been running unattended for a while.

The DIY route: Raspberry Pi kiosk mode with Chromium autostart

These steps assume a current Raspberry Pi OS (formerly Raspbian) with desktop: Bookworm or later, using Wayfire or labwc on Wayland, or Openbox on X11.

Step 1: install Chromium and a cursor hider

Install Chromium and unclutter (to hide the cursor on X11) if they are not already present:

sudo apt update
sudo apt install -y chromium-browser unclutter

On newer releases the package may be called chromium instead of chromium-browser. If apt cannot find one name, try the other. unclutter only works on X11; the Wayland equivalents are covered in Step 4.

Step 2: set boot and display options

Open sudo raspi-config and set the Pi to boot to the desktop with auto-login enabled. In the same tool, disable screen blanking. Under Advanced Options, the Wayland entry lets you choose between X11, Wayfire and labwc; recent Bookworm images default to labwc. If you are not sure what you are running, open a terminal on the desktop and type echo $XDG_SESSION_TYPE: it prints x11 or wayland. On X11 you can also add xset s off -dpms to your kiosk script so the screen never goes to sleep.

Step 3: write the launch command

A minimal Chromium kiosk command looks like this:

chromium-browser --noerrdialogs --disable-infobars --kiosk --incognito \
 --autoplay-policy=no-user-gesture-required http://your-content-url

The flags that matter:

• --kiosk removes the browser UI and forces full screen.
• --noerrdialogs suppresses crash and restore prompts that would otherwise sit on top of your content.
• --incognito avoids accumulating cache and cookies across reboots.
• --disable-infobars hides notification bars such as translation prompts.
• --autoplay-policy=no-user-gesture-required lets videos start without someone clicking first.

Step 4: make it auto-start and restart itself

Do not point autostart at Chromium directly. Point it at a small wrapper script, so a crashed browser comes back:

#!/bin/bash
while true; do
  chromium-browser --noerrdialogs --disable-infobars --kiosk --incognito \
   --autoplay-policy=no-user-gesture-required http://your-content-url
  sleep 5
done

Save it as ~/kiosk.sh and run chmod +x ~/kiosk.sh. Then call it from the autostart file of whichever session you run. The examples use the user pi; replace /home/pi with your own home directory.

On labwc (Wayland, the current default), add this line to ~/.config/labwc/autostart, creating the file if it does not exist:

/home/pi/kiosk.sh &

The trailing & matters: without it, labwc waits for the endless loop and anything listed after it never starts.

On Wayfire (Wayland), open ~/.config/wayfire.ini and add an entry to the [autostart] section:

[autostart]
kiosk = /home/pi/kiosk.sh

On X11 (LXDE-pi with Openbox), add @/home/pi/kiosk.sh and @unclutter -idle 0.5 to ~/.config/lxsession/LXDE-pi/autostart.

Hiding the cursor on Wayland takes a different tool per compositor. On Wayfire, install the wayfire-plugins-extra package and add hide-cursor to the plugins line in the [core] section of wayfire.ini. On labwc, use the HideCursor action (labwc 0.7.2 and later): bind it to a key in ~/.config/labwc/rc.xml and trigger that key once at startup with a tool such as wtype from your autostart file.

If you prefer systemd over the loop, the part that trips people up is the graphical session: a service started as root before the desktop is up has no display to draw on, so Chromium exits immediately and restarts forever. A minimal unit at /etc/systemd/system/kiosk.service looks like this:

[Unit]
Description=Chromium kiosk
After=graphical.target
Wants=graphical.target

[Service]
User=pi
Environment=DISPLAY=:0
Environment=WAYLAND_DISPLAY=wayland-0
Environment=XDG_RUNTIME_DIR=/run/user/1000
ExecStart=/usr/bin/chromium-browser --noerrdialogs --disable-infobars --kiosk --incognito --autoplay-policy=no-user-gesture-required http://your-content-url
Restart=always
RestartSec=5

[Install]
WantedBy=graphical.target

Check the real socket name by running echo $WAYLAND_DISPLAY in a desktop terminal (Wayfire often uses wayland-1), and confirm your user ID with id -u. Enable it with sudo systemctl enable --now kiosk.service, read logs with journalctl -u kiosk, and remove the autostart entry so you do not end up with two Chromium windows.

Step 5: test the ugly cases

Reboot, and if everything lines up, the Pi comes up in kiosk mode on its own. Then pull the network cable for a minute, kill Chromium with pkill chromium, and yank the power. If any of those three leaves a black screen or an error page, go back to Step 4 before you mount the TV.

For deeper reference on boot configuration and display settings, the official Raspberry Pi documentation is the most reliable source. Screen and boot options change between OS releases, so check it against whatever version you are running.

Common Raspberry Pi kiosk mode problems

The setup above works fine on day one. The failures show up later, and they are the same handful every time:

• Chromium crashes silently. Without a restart loop or watchdog, the screen goes black and stays black until someone notices and power-cycles it.
• Network blips leave a "no internet" page on screen until the browser is restarted.
• OS updates change the autostart mechanism. Entries in ~/.config/lxsession/LXDE-pi/autostart are ignored under Wayfire and labwc, so a Pi upgraded or reflashed onto a Wayland session boots to an empty desktop.
• The TV stays on 24/7 because nothing is driving HDMI-CEC, which wastes power overnight.
• Content updates require SSH. If the display shows a local file or a hardcoded URL, changing it means plugging in a keyboard or logging in remotely, which is awkward for a shop floor five Pis deep.

None of these are hard to fix individually. The restart loop handles crashes, a cron job can restart Chromium nightly to clear a stuck error page, and a smart plug can handle TV power. But each fix is another thing to configure and maintain on every Pi you deploy. For deeper fault-finding, see the Raspberry Pi signage troubleshooting guide.

TVpilot vs DIY: a comparison

Say you run a café with two Pis: one menu board, one promo screen. DIY costs nothing in software, but every menu change means editing a URL or file on each Pi, and nobody knows a screen has frozen until a customer mentions it. On TVpilot, two screens fit on the Starter plan, the menu change happens from a laptop, and both TVs go to standby after closing on a schedule.

If you enjoy the scripting and only need one or two signs that rarely change, DIY is genuinely fine. There is no need to pay for something you can maintain yourself in an afternoon.

When TVpilot is (and isn't) the right fit

TVpilot makes sense if you run more than a couple of screens, if the people changing content are not the people who can SSH into a Pi, or if your screens sit in different rooms or branches where walking over with a keyboard is a chore.

It is not the right fit if you specifically want a self-hosted or open-source stack, or if the Pi needs to keep receiving fresh content with no internet connection at all. The player recovers automatically after an outage, but it still needs connectivity to receive updates. On other devices: Fire TV and the Amazon Signage Stick have a TVpilot app in the Amazon Appstore, while Android TV has no Google Play app and runs through the browser route with the player URL.

Skip the manual setup

If you would rather not maintain scripts on every Pi, TVpilot's installer does the five steps above in one go. You generate a single command in the TVpilot dashboard, tied to a 6-character claim code, and paste it into the Pi's terminal. It sets up:

• Chromium kiosk mode pointed at your TVpilot player.
• Auto-start on X11 or Wayland, plus a systemd service.
• A self-healing watchdog that restarts the player within about 10 seconds if it stops.
• Quiet boot and a hidden cursor, so no boot text or pointer ever shows on the TV.

On top of the kiosk itself, the player checks the dashboard power schedule every minute and switches the TV on or to standby over HDMI-CEC, runs a daily update check at 03:00, and can be updated or rebooted remotely from the dashboard. Content (images, videos, web pages and PDFs in playlists) is managed from the browser, and screen monitoring shows online/offline status and heartbeats, so you know a Pi went dark before a customer tells you.

Any Pi running Raspberry Pi OS with a desktop works; a Pi 4 or 5 is recommended for smooth video. The Raspberry Pi setup page walks through the installer. The Free plan is €0 forever for 1 screen with 250 MB of storage and no credit card. When you need more screens, Starter is €5/month for 3 screens included (up to 10) and Pro is €29/month for 10 screens included (up to 100), with custom Business pricing above that.

Getting started

To get a working kiosk with remote content control in a few minutes, create a free account, generate the install command with your claim code, and paste it into your first Pi.