Skip to content

Instantly share code, notes, and snippets.

@lellky
Created March 14, 2025 08:53
Show Gist options
  • Select an option

  • Save lellky/673d84260dfa26fa9b57287e0f67d09e to your computer and use it in GitHub Desktop.

Select an option

Save lellky/673d84260dfa26fa9b57287e0f67d09e to your computer and use it in GitHub Desktop.
How to run Chromium in kiosk mode on a Raspberry Pi 2025

How to run Chromium in Kiosk mode on Pi 2025

Update the system

sudo apt update && sudo apt upgrade and sudo reboot to get the latest and greatest of the software.

Configuration

After that the Pi must be configured to boot into CLI-mode and log in.

sudo raspi-config. Choose System options -> Boot / Auto Login -> B2 Console Autologin

Software that is needed

Install xserver and openbox (probably already installed) with sudo apt-get install --no-install-recommends xserver-xorg x11-xserver-utils xinit openbox and then Chromium browser (also probably already installed) with sudo apt-get install --no-install-recommends chromium-browser.

More configuration

sudo vim /etc/xdg/openbox/autostart. Add the following content:

# Configuration
WEBSITE_URL="https://PUT_YOUR_WEBSITE_ADDRESS_HERE"

# Disable screensaver, screen blanking, and power management
xset s off
xset s noblank
xset -dpms

# Auto-detect screen resolution
RESOLUTION=$(xrandr 2>/dev/null | grep '*' | awk '{print $1}')
if [ -z "$RESOLUTION" ]; then
    RESOLUTION="1920x1080"  # Default fallback can be ="1280x720"
fi
SCREEN_WIDTH=$(echo $RESOLUTION | cut -d 'x' -f1)
SCREEN_HEIGHT=$(echo $RESOLUTION | cut -d 'x' -f2)

echo "Detected screen resolution: ${SCREEN_WIDTH}x${SCREEN_HEIGHT}"

# Check internet connection using ping before launching Chromium
if ping -c 1 -W 2 google.com >/dev/null 2>&1; then
    echo "Internet connected. Proceeding with Chromium launch."
else
    echo "No internet connection detected. Exiting."
fi

# Allow quitting the X server with CTRL-ALT-Backspace
# setxkbmap -option terminate:ctrl_alt_bksp

# Prevent Chromium restore prompts
sed -i 's/"exited_cleanly":false/"exited_cleanly":true/' ~/.config/chromium/'Local State'
sed -i 's/"exit_type":"[^"]\+"/"exit_type":"Normal"/' ~/.config/chromium/Default/Preferences

# Clean up Chromium cache, cookies, and logs
find ~/.config/chromium/Default/ -type f \( -name "Cookies" -o -name "History" -o -name "*.log" -o -name "*.ldb" -o -name "*.sqlite" \) -delete
rm -rf ~/.config/chromium/Default/Logs/*

# Clear system logs
sudo journalctl --vacuum-time=1d
sudo find /var/log -type f \( -name "*.log" -o -name "*.gz" -o -name "*.1" \) -delete
sudo truncate -s 0 /var/log/syslog /var/log/dmesg

# Kill any existing Chromium instances
pkill -9 chromium-browser 2>/dev/null
pkill -9 chrome 2>/dev/null

# Start Chromium in kiosk mode
chromium-browser --kiosk --disable-gpu --noerrdialogs --disable-infobars --disable-features=TranslateUI \
    --disable-session-crashed-bubble --no-sandbox --disable-notifications --disable-sync-preferences \
    --disable-background-mode --disable-popup-blocking --no-first-run \
    --enable-gpu-rasterization --disable-translate --disable-logging --disable-default-apps \
    --disable-extensions --disable-crash-reporter --disable-pdf-extension --disable-new-tab-first-run \
    --disable-dev-shm-usage --start-maximized --mute-audio --disable-crashpad --hide-scrollbars \
    --ash-hide-cursor --memory-pressure-off --force-device-scale-factor=1 --window-position=0,0 \
    --window-size=${SCREEN_WIDTH},${SCREEN_HEIGHT} "$WEBSITE_URL" &

if [ $? -eq 0 ]; then
    echo "Chromium started successfully."
else
    echo "Failed to start Chromium."
    sudo reboot
fi

And then sudo vim .bash_profile and add the following: add [[ -z $DISPLAY && $XDG_VTNR -eq 1 ]] && startx -- -nocursor

And finally a crucial step (without this the normal desktop environment is launched): sudo update-alternatives --config x-session-manager and choose "/usr/bin/openbox-session".

@Ironborn65

Copy link
Copy Markdown

:(

@lellky

lellky commented Dec 1, 2025

Copy link
Copy Markdown
Author

What do you mean? Does it not work for you?

@JJetmar

JJetmar commented Dec 3, 2025

Copy link
Copy Markdown

In my installation I needed to run just chromium instead of chromium-browser.

@lellky

lellky commented Dec 3, 2025

Copy link
Copy Markdown
Author

Ok! 👍

@tofuservices

tofuservices commented Jan 25, 2026

Copy link
Copy Markdown

Could you please help? Does not work for me. I also changed chromium-browser to chromium since chromium-browser seems to be the incorrect package name, but despite this, I still boot into the desktop environment. Also, rather than vim I used sudoedit, but don't think this will affect anything. Thanks a lot!

Edit: So after double checking for errors, even booting into the console rather than the desktop (for me labelled differently from your how-to), it boots to console and nothing happens.

@lellky

lellky commented Jan 26, 2026

Copy link
Copy Markdown
Author

Could you please help? Does not work for me. I also changed chromium-browser to chromium since chromium-browser seems to be the incorrect package name, but despite this, I still boot into the desktop environment. Also, rather than vim I used sudoedit, but don't think this will affect anything. Thanks a lot!

Edit: So after double checking for errors, even booting into the console rather than the desktop (for me labelled differently from your how-to), it boots to console and nothing happens.

Did you do this? sudo update-alternatives --config x-session-manager

@libbymiller

Copy link
Copy Markdown

Thank you for this, very handy.
In case it helps anyone - in bookworm today I had to go to raspi-config and switch to advanced->wayland->openbox with x11 backend
I also added --password-store=basic to the Chromium flags to stop an annoying popup.

@lellky

lellky commented Jul 7, 2026

Copy link
Copy Markdown
Author

Great addition! Thanks.

@rgrichva

Copy link
Copy Markdown

I followed your instructions but when the startx command executes on boot up X fails to start with the following error:
Fatal severe error:
parse_vt_settings: Cannot open /dev/tty0 (permission denied)

But if I go to the console terminal window and enter startx -- -nocursor my application starts up and displays normally.
I've seen others with a similar problem but haven't found anything that works. Seems to be related to the autostart and who is executing the startx command (system on boot up or user after boot is complete)
loginctl shows that auto login user is attached to tty1

Any thoughts on why this is happening and a possible fix?
Thanks

@lellky

lellky commented Aug 26, 2026

Copy link
Copy Markdown
Author

My Codex agent looked into this, and since the exact same startx command works when you run it manually a few seconds later, Chromium and Openbox are probably configured correctly. The most likely cause is a timing issue: .bash_profile starts X before the automatically logged-in session is fully active and has been granted access to the virtual terminal by systemd-logind.

Could you try replacing the startx line in ~/.bash_profile with this?

if [ -z "$DISPLAY" ] && [ "$(tty)" = "/dev/tty1" ]; then
    sleep 3
    exec startx -- -nocursor
fi

If the delay fixes it, that confirms it is a race during login.

If it still fails, these commands should provide useful information:

tty
id
ls -l /dev/tty0 /dev/tty1
echo "$XDG_SESSION_ID $XDG_VTNR"
loginctl show-session "$XDG_SESSION_ID" -p Active -p Remote -p TTY
cat ~/.local/share/xorg/Xorg.0.log
dpkg -l xserver-xorg-legacy
cat /etc/X11/Xwrapper.config

As a fallback, you could install the legacy Xorg wrapper:

sudo apt install xserver-xorg-legacy

Then set /etc/X11/Xwrapper.config to:

allowed_users=console
needs_root_rights=yes

I would test the short delay first, though. I would also avoid sudo startx, since that would run the X session—and potentially Chromium—as root.

Please let me know whether adding the delay changes anything.

@rgrichva

Copy link
Copy Markdown

Found the issue was my problem I had backgrounded the exec startx once I removed the "&" it worked as expected.
Thanks for looking into this and all the suggestions.

@lellky

lellky commented Aug 26, 2026

Copy link
Copy Markdown
Author

@rgrichva glad to hear that it worked out!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment