LibreDisplay

Your home. Your dashboard. Your data.
A free, open-source home dashboard for Raspberry Pi, Docker, NAS, mini PCs, and browsers.

LibreDisplay brings calendars, weather, photos, family chores, tasks, media, charts, alerts, and custom data together on one clean display. It is designed to stay simple for everyday use while keeping advanced controls out of the way until you need them.

Quick start — Raspberry Pi

Best choice for a dedicated wall display. Use a current Raspberry Pi OS with Desktop.

Open Terminal, then run these commands one at a time, in order. You can copy and paste each box separately.

1. Update Raspberry Pi OS package information:

sudo apt update

2. Install the small tools needed for setup:

sudo apt install -y curl unzip

3. Create a clean LibreDisplay setup folder:

rm -rf ~/LibreDisplay-Setup && mkdir -p ~/LibreDisplay-Setup

4. Download the latest LibreDisplay release:

curl -fL https://github.com/Gubna-Tech/LibreDisplay/archive/refs/tags/v1.5.4.zip -o /tmp/LibreDisplay.zip

5. Extract LibreDisplay:

unzip -q /tmp/LibreDisplay.zip -d ~/LibreDisplay-Setup

6. Open the LibreDisplay setup folder:

cd ~/LibreDisplay-Setup/LibreDisplay-1.5.4

7. Allow the installer to run:

chmod +x install.sh

8. Start the installer:

./install.sh

That is it. Reboot when prompted and LibreDisplay will open automatically.

Raspberry Pi OS Lite is not supported by the native kiosk installer. Use Raspberry Pi OS with Desktop, or run LibreDisplay with Docker instead.

First setup

A new installation opens LibreDisplay's guided setup automatically. The wizard uses the same real Settings controls as the full configuration screen, so there is no separate hidden setup format to keep in sync.

The guided flow walks through:

1. Display name — give the screen a clear room/purpose name for multi-display management.
2. Weather location — search and choose the exact city/region/country result, including verified coordinates and timezone.
3. Calendars — add ICS feeds or import local .ics files, or skip calendars entirely.
4. Background — choose stock images, Google Photos, local/NAS folders, or no photo background.
5. Weather alerts and appearance — choose the essentials without entering the power-user layout controls.
6. Remote management — optionally enable pairing on a trusted LAN/private VPN.
7. Recovery — optionally create an Initial setup baseline restore point immediately after the configuration is saved.
8. Review & health check — save once, then verify server persistence, weather, calendars, background readiness, remote access, recovery, host health, and software status.

Experienced users can choose Open full settings at any point and configure LibreDisplay directly. The wizard can also be rerun later from Settings > Home > Run setup wizard.

Settings open in the simpler Essentials view by default. Switch to All only when you want advanced and troubleshooting options.

Everyday use

LibreDisplay is designed to run quietly in the background. Once configured, your display updates itself and the Settings button stays out of the way.

Useful places to remember:

• Weather — location, forecasts, details, and severe-weather alerts
• Calendars — calendar feeds, imported ICS files, and event display rules
• Backgrounds — photo sources, local/NAS folders, and slideshow behavior
• Family — household members, chores, points, and rewards
• Personalization — themes, templates, typography, and accessibility
• Layout — visual layout presets with schematic previews, full-screen live preview, dashboard visibility, geometry, and the Arrange editor
• Arrange editor — move/resize blocks, drag the inspector out of the way, and fine-tune individual text sections such as calendar event titles/times without changing day/date headers. When editing remotely, Arrange waits for a fresh wall-display heartbeat and mirrors the Pi’s actual dashboard viewport. The target canvas is scaled independently while the editor toolbar and inspector stay at normal laptop size, so editing controls remain readable and selectable without changing the dashboard geometry.
• Integrations — connect supported services and check their status
• System — host health, software updates, displays, display profiles, accounts, backups, diagnostics, remote access, and advanced options

Small ? buttons beside less-obvious controls provide quick hover/click help without filling the interface with extra instructions.

Display profiles and templates

Open Settings > System > Display profiles to save a known-good dashboard as a named profile, duplicate it before experimenting, capture another configured display as a profile, or explicitly apply a profile to a selected display. Profile application is per-display and never edits the saved profile itself. Scenes & schedules can continue using those profiles for time-based switching.

Layout presets are shown as visual cards so you can see the intended arrangement before trying it. The expanded layout library includes original family-command, split photo/planner, gallery-first, calendar-wall, planner-rail, weather-center, across-the-room, compact-tablet, minimal-photo, and portrait compositions, plus showcase screens for Morning Briefing, Smart Home Hub, Family Operations, Team Board, Markets & Conditions, and Travel Day. These showcase layouts demonstrate how LibreDisplay can combine configured integrations such as Home Assistant, Spotify/Sonos, task services, Slack, RSS, package tracking, market data, transit/travel data, and maps. Compatible blocks you already configured can snap into the labeled showcase slots during preview and when you apply that showcase layout; empty slots are visual suggestions only and are never saved as fake data. Credentials and provider configuration are never replaced. Each preset carries a tuned content-density profile—calendar range and columns, forecast range, typography, spacing, alignment, and responsive content fitting—so complete calendar and forecast content remains visible instead of squeezing or clipping inside smaller blocks. Selecting a preset stages only the LibreDisplay presentation; choose Preview selected layout to inspect it full-screen with your real dashboard content. The saved display is untouched until Save & Apply. Applying a preset replaces prior built-in Arrange positions/alignment and the preset-controlled density values, while accounts, data sources, integrations, theme, background, and unmatched custom blocks remain intact. Cancel/Esc restores the exact saved layout. Starter templates use the same preview pipeline while also staging their documented presentation settings; Weather Details selection/order and data-source/account configuration remain preserved.

Updating LibreDisplay

Native Raspberry Pi installations check the official GitHub releases automatically whenever Settings opens and every 15 minutes while Settings remains open. Settings > System > Software update still includes Check now for an immediate manual refresh. When a newer release is available, owners see an update notice and can choose Update now. LibreDisplay creates a safety backup, downloads the official release, keeps your settings, media, and custom plugins, installs the update, and restarts the device.

The terminal updater remains available as a recovery/advanced path:

libredisplay check

libredisplay update

The first upgrade from a pre-v1.5.0 release may ask for sudo in Terminal once so LibreDisplay can install its narrowly scoped update helper. After that, supported native installations can install future releases from Settings without entering a terminal command. Automatic unattended updates are not enabled; installing an update always requires an explicit owner action.

Docker installations still update from the Docker host with ./scripts/docker-setup.sh update; LibreDisplay shows available releases in Settings but does not attempt to rebuild its own host container.

Update history and version rollback

Supported native updates now create a private pre-update rollback snapshot before replacing application files. Open Settings > System > Update history & rollback to see the previous release snapshots retained on the Pi. LibreDisplay keeps the newest five automatically.

A version rollback is intentionally stronger than a normal Settings restore point: it verifies the stored snapshot, first creates a fresh recovery snapshot of the current installation, then restores the previous LibreDisplay application together with the settings, media, plugins, and project .env captured immediately before that update. The device restarts afterward. This makes a bad release recoverable without requiring a terminal while still keeping the state you are rolling back from recoverable.

Rollback snapshots are private local maintenance data and are not exposed to display/viewer sessions. Docker rollback remains host-managed because a container should not replace its own host deployment.

System health and diagnostics

Open Settings > System > Data sources & providers for one privacy-safe troubleshooting view of weather, calendar feeds, background sources, weather alerts, integrations, and remote-data cache fallback. LibreDisplay distinguishes healthy, delayed/cached, misconfigured, and failed sources without displaying private URLs, tokens, or coordinates.

Open Settings > System > System health to see the deployment type, host uptime, free storage, data-directory write status, platform, and load average. The Home page also keeps a compact health summary for weather, calendars, backgrounds, alerts, integrations, offline cache, and software updates.

For support or troubleshooting, choose Download diagnostics. The generated JSON intentionally omits private calendar/background URLs, integration credentials, and weather coordinates, while keeping useful version, provider state, refresh timing, cache state, layout, recovery, and host-health information.

Display readiness and kiosk resilience

Open Settings > System > Display readiness & kiosk resilience to check the target screen without changing its layout. LibreDisplay reports the currently observed viewport, portrait/landscape orientation, browser visual scale/device-pixel ratio, and the most recent local kiosk heartbeat. It warns when a viewport is unusually small or browser scaling is not at 100%, which helps separate display/zoom problems from saved Arrange geometry.

Native kiosk installations now have two local watchdogs in scripts/start.sh: the server is restarted after repeated /healthz failures, and Chromium is restarted when the local dashboard heartbeat stops advancing while the browser process is still alive. The browser heartbeat contains only local endpoint/version/viewport timing information. The screen-side page also tracks EventSource/network state, continues showing last-known cached provider data while disconnected, and automatically refreshes saved configuration/data when the LibreDisplay server reconnects. Screen-only Viewer installs keep Chromium background timers/rendering enabled so long-running weather/calendar refreshes are not throttled simply because the window is kiosked.

Under Settings > Personalization > Accessibility & language, optional Always-on display care can dim the entire rendered screen after 15, 30, 60, or 120 minutes without local interaction. Any pointer, touch, wheel, or keyboard interaction wakes it immediately. This uses a non-interactive overlay only: it does not move, resize, or rewrite any saved Arrange element. Screen care is off by default.

Portable backups and restore points

Open Settings > System > Backup & recovery for day-to-day migration and rollback tools:

• Export portable backup downloads this display's saved configuration, the server's Profiles, and only this display's Scene rules as JSON. It is intended for moving a setup between LibreDisplay installations without copying media, account passwords, pairing secrets, or host/NAS credentials.
• Import portable backup creates a local safety restore point first, then imports the saved display configuration, merges the bundled Profiles, and replaces only the current display's Scene rules while leaving other displays' Scene rules intact.
• Local restore points keep up to 20 private snapshots on the LibreDisplay host so you can return to a known-good configuration after experimentation. They include the current display configuration plus the server-wide Profiles and Scenes stores; restoring one can therefore affect scheduled profiles used by other displays. Restoring a point automatically creates a new Before restore point first.

Portable JSON may still contain private calendar URLs or integration credentials from the display configuration, so store it securely. For a complete machine/server backup including media, plugins, .env, pairing/account data, or managed NAS host state, keep using the full .ldbackup tools documented below.

Docker

Docker is a good choice when LibreDisplay runs from a NAS, mini PC, or home server and your screens connect through a browser.

From the extracted LibreDisplay folder, run these commands one at a time, in order.

1. Allow the Docker setup helper to run:

chmod +x scripts/docker-setup.sh

2. Start LibreDisplay for your home network:

./scripts/docker-setup.sh --lan

Then open the address shown by the script on a trusted device on your home network.

Updating a Docker installation

From the existing LibreDisplay Docker folder, run:

./scripts/docker-setup.sh update

The Docker updater checks the latest GitHub release, stops LibreDisplay before taking a safety backup, preserves data, media, .env, and custom plugin folders, replaces only release-managed source files, rebuilds the container, and waits for its health check. If the new deployment cannot start cleanly, the previous source is restored automatically. Safety backups are kept under ./backups.

Docker self-update starts with v1.2.0. Docker installations older than v1.2.0 need one manual move to the v1.2.0 release files before this command is available; updates after that use the command above.

To make a Docker backup without updating, run:

./scripts/docker-setup.sh backup

Rerunning ./scripts/docker-setup.sh start keeps existing Docker UID/GID and advanced .env values instead of resetting them.

Add a screen-only Raspberry Pi to a Docker server

1. On the LibreDisplay server, show the available Display Links:

./scripts/docker-setup.sh links

Copy the Display Link for the screen you want to use.

On the viewer Raspberry Pi, run the next commands one at a time, in order.

2. Download the viewer setup helper:

curl -fL https://raw.githubusercontent.com/Gubna-Tech/LibreDisplay/v1.5.4/scripts/viewer-setup.sh -o /tmp/libredisplay-viewer-setup.sh

3. Allow the viewer installer to run:

chmod +x /tmp/libredisplay-viewer-setup.sh

4. Install the Display Link:

/tmp/libredisplay-viewer-setup.sh install 'PASTE_DISPLAY_LINK_HERE'

What LibreDisplay includes

• Calendars and imported ICS files
• Weather, alerts, UV, pollen, tides, and personal weather stations
• Local folders, NAS photos, OneDrive, Dropbox, Box, Flickr, and public iCloud Shared Albums
• Todoist, Google Tasks, Microsoft To Do, CalDAV/Nextcloud Tasks, Trello, and Asana
• Family/touch mode with recurring chores, points, rewards, and optional PIN protection
• YouTube, Vimeo, Spotify now-playing, and Sonos now-playing
• Stocks, crypto, currency, traffic/travel time, transit, maps, package tracking, and flight status
• Fitbit activity and Slack messages
• Value cards, gauges, progress bars, sparklines, line charts, bar charts, and tables
• Multiple displays from one server
• Owner, Editor, and Viewer roles with optional display restrictions
• Full backup/restore
• Local folders and read-only NAS storage
• Raspberry Pi kiosk mode and Docker deployment

Calendars, photos, and multiple displays

Calendars

Go to Settings > Calendars > Calendars > Add calendar.

LibreDisplay accepts normal ICS/iCalendar subscription links, including links from Google Calendar, Proton Calendar, Outlook/Microsoft 365, iCloud shared calendars, Nextcloud, Fastmail, and other compatible providers. webcal:// links work too.

You can also import a local .ics file.

Photos and NAS folders

For another local photo folder:

~/libredisplay/scripts/setup-media.sh

For an SMB/CIFS or NFS share:

~/libredisplay/scripts/setup-nas.sh

Then choose the folder under Settings > Backgrounds > Pictures & Backgrounds.

Multiple displays

Go to Settings > Home > Displays > Add display.

Each display can have its own calendars, weather, photos, theme, layout, and read-only Display Link. One LibreDisplay server can therefore run a kitchen screen, office screen, bedroom screen, and more without separate server installations.

Integrations

Open Settings > Integrations to browse the integrations installed with LibreDisplay. Configured blocks show live connection health, refresh interval, last successful refresh, last connection check, cached/stale state, and a privacy-safe error category when something fails. Test connection forces a live provider request while preserving the last known good cache if the provider is temporarily offline. Test all configured checks multiple providers with limited concurrency so troubleshooting does not flood external services. Saved credentials are never rendered in the health payload.

Included integrations cover:

• Home Assistant
• Todoist
• CalDAV / Nextcloud Tasks
• Google Tasks
• Microsoft To Do
• Trello
• Asana
• Sonos
• Spotify
• OneDrive Photos
• Dropbox Photos
• Box Photos
• Flickr Photos
• iCloud Shared Albums
• Alpha Vantage stocks
• CoinGecko crypto
• Frankfurter currency
• Mapbox travel time
• OpenStreetMap
• GTFS-Realtime transit
• AfterShip package tracking
• aviationstack flight status
• Google Pollen
• Open-Meteo UV
• NOAA tides
• Weather Company personal weather stations
• Fitbit
• Slack
• Generic Web API data

Some providers require your own API key or OAuth credentials. LibreDisplay stores provider credentials on the server and strips them from read-only display responses.

Backup and restore

For normal configuration migration or a quick settings rollback, use Settings > System > Backup & recovery first. Portable backups move one display's configuration plus Profiles and Scenes, while local restore points provide fast on-device configuration rollback without touching media or host secrets. To return the entire native installation to a previous LibreDisplay release after an update, use Settings > System > Update history & rollback instead.

For a full native Raspberry Pi installation backup, create a sensitive .ldbackup with:

~/libredisplay/scripts/backup.sh

Native backups are stored under ~/libredisplay-backups/ by default. For a Docker installation, use:

./scripts/docker-setup.sh backup

Docker backups are stored under ./backups in the LibreDisplay Docker folder.

For a native Raspberry Pi installation, restore one with:

~/libredisplay/scripts/restore.sh ~/libredisplay-backups/YOUR-BACKUP.ldbackup

A full backup can contain passwords, API tokens, display links, settings, media, and plugins. Keep it private.

If you use LibreDisplay-managed NAS mounts and want their host settings included too:

sudo ~/libredisplay/scripts/backup.sh --include-host

Remote access, accounts, and privacy

LibreDisplay is designed for a trusted home network or private VPN. Native Raspberry Pi remote editing is off by default.

Available local roles:

• Owner — full administration
• Editor — can edit assigned displays
• Viewer — can view assigned displays only

The physical local display remains Owner access. Each display also has a dedicated read-only Display Link.

Do not port-forward LibreDisplay directly to the public Internet. Use a private VPN such as WireGuard or Tailscale if you need remote access.

LibreDisplay does not require a LibreDisplay cloud account and does not include telemetry. External integrations only contact the services you choose to configure.

If you discover a security issue, please report it privately to the project owner rather than posting exploit details publicly.

Troubleshooting

Start LibreDisplay manually:

~/libredisplay/scripts/start.sh

Check that the local server is running:

curl http://127.0.0.1:8787/healthz

If a remote display does not connect, make sure both devices are on the same trusted network and that remote access is enabled when required.

Uninstall LibreDisplay

Remove LibreDisplay while preserving a copy of dashboard data and local project media:

~/libredisplay/uninstall.sh

Completely erase LibreDisplay-managed application data and backups:

1. Run the purge uninstall:

~/libredisplay/uninstall.sh --purge

2. After the uninstall finishes, reboot:

sudo reboot

Photos stored outside LibreDisplay or on a NAS are not intentionally deleted.

Open source

LibreDisplay is released under the MIT License.

Copyright (c) 2026 Gubna.