Raspberry Pi Kiosk Mode using Raspbian Lite

Setting up a Raspberry Pi to run in kiosk mode using Raspbian Lite

Last updated: 2019-09-06.

Download the latest Rasbian Lite from the Raspberry Pi Foundation and unpack it so you've got a .img file.

Set up the SD card

I recommend using Etcher rather than the method below - it's quicker.

NOTE: The following section is a truncated version of the Mac instructions from the Raspberry Pi Foundation. Instructions for other operating systems (or further details for Mac users if the below fails) are available here: https://www.raspberrypi.org/documentation/installation/installing-images/README.md.

  • Open a terminal window and run: diskutil list
  • From the list identify the disk (not partition) of your SD card in this instance it is disk4:
Output of diskutil list
  • Unmount the SD card diskutil unmountDisk /dev/disk<NUMBER>
  • Copy the data to the card sudo dd bs=1m if=route/to/disk/image.img of=/dev/rdisk<NUMBER>
  • Wait. There will be no on screen info during this time.
  • Run: sudo diskutil eject /dev/rdisk then remove the disk from your computer and plug it into your Pi.

Setting up the Pi

The default login is set to:

  • Username: pi
  • Password: raspberry


This is worth doing as if you have a short piece of network cable you can create a direct connection between your pi and your main computer, allowing you to use your full keyboard and screen to set up your pi. Cool huh? If you have a screen and keyboard you can setup SSH using raspi-config:

  1. type sudo raspi-config
  2. select interfacing options
  3. select SSH
  4. choose Yes
  5. select OK
  6. choose finish

Running headless? In that case you will want to create a file named ssh on the boot partition of the SD card. When the Pi boots, it looks for the 'ssh' file. If it is found, SSH is enabled, and the file is deleted. The content of the file does not matter: it could contain text, or nothing at all. Do these instructions look familiar? They're the same ones as appear here: https://www.raspberrypi.org/documentation/remote-access/ssh/.

Finding the IP address of your pi

If you have a monitor to hand the simplest way to find your ip address is to boot the pi and type hostname -I. If you're running headless you probably want to use nmap as per the instructions on the raspberry pi foundation.

NB it is possible (and quicker) to use ssh <username>@raspberrypi.local when connecting directly to your pi.

Code editor

If like me, you have a preference as to text editor you will want to install that next: sudo apt install vim

Check everything's up-to-date

Even though you only just downloaded the disk image you will want to run the following: sudo apt update && sudo apt -y upgrade

Install the stuff you need in order to have a GUI

sudo apt install --no-install-recommends xserver-xorg xinit xserver-xorg-video-fbdev lxde lxde-common lightdm

  • --no-install-recommends stops it installing ALL THE THINGS which it will otherwise do.
  • x gives you a screen session
  • lxde gives you the UI
  • light dm is the login manager

Do some configuration

Type sudo raspi-config into the command line and do the following:

  1. Expand the file system: Advanced Options > Expand Filesystem.
  2. Disable overscan: Advanced Options > Disable Overscan. This helps ensure the display fills the entire screen rather than leaving black bars down the sides.

Install Chromium Browser and unclutter (removes the cursor)

sudo apt install chromium-browser unclutter


sudo vim /etc/lightdm/lightdm.conf

Then uncomment and amend the following lines so that they match the below:

autologin-user=pi autologin-user-timeout=0

Setup your .xsession script

If you don't have a .xsession file in /home/pi/ then create one and add the following to it EDIT: now incorporating additions by @thinkl33t to set the browser size automatically.:

# Set this to your URL - it must return a 200 OK when called, not a redirect.
export URL={{kiosk.url}}

# Don\'t want screensavers or screen blanking
xset s off &
xset -dpms &
xset s noblank &

# Hide the mouse cursor
unclutter -idle 10 -noevents &

# Sit and wait until you can hit the URL you\'ll be showing in the kiosk
while ! curl -s -o /dev/null -w "%{http_code}" ${URL} | grep -q "200"; do
  sleep 1

# get screen resolution
WIDTH=`sudo fbset -s | grep "geometry" | cut -d " " -f6`
HEIGHT=`sudo fbset -s | grep "geometry" | cut -d " " -f7`

# Open chrome in incognito mode + kiosk mode
/usr/bin/chromium-browser --window-size=${WIDTH},${HEIGHT} --window-position=0,0 --incognito --kiosk ${URL}

Chromium swatches

Jacob told me about these in the comments on my original unedited WP post as I was originally using a settings file that no longer exists to set the size of the browser. He didn't leave a URL so I can't easily link him until I manage to get my comments up and running again.

If you need to set other options on launch you're best having a look at Peter Beverloo's awesomely useful list of chromium command line swatches.

Make sure everything works

Reboot: sudo reboot.

Things I read in order to make this happen (that aren't explicitly mentioned above)

Thanks everyone :)

Comments powered by Talkyard.