Home Assistant on Raspberry Pi

Why Raspberry Pi for Home Assistant?

The Raspberry Pi is the most popular hardware platform for Home Assistant. It is cheap, silent, power-efficient (~5W), and has USB and GPIO ports for connecting Zigbee/Z-Wave dongles and sensors directly. The Home Assistant project officially supports the Pi and publishes a dedicated operating system image for it.

There are two installation methods, and the right choice depends on whether the Pi is dedicated to Home Assistant or shared with other workloads.

HAOS (Home Assistant Operating System) is the recommended method for a dedicated Pi. It gives you the full Home Assistant experience: Supervisor, Add-on Store, managed backups, automatic updates, and the simplest setup path. The trade-off is that HAOS takes over the entire device.

Docker Container is the alternative if you already run Raspberry Pi OS with other services. You get Home Assistant Core in a container alongside everything else, but you lose the Supervisor, Add-on Store, and managed backups.

This guide covers both methods. Start with HAOS unless you have a specific reason for Docker.

Prerequisites

Hardware

Component	Minimum	Recommended
Board	Raspberry Pi 4 (2 GB)	Raspberry Pi 5 (4 GB or 8 GB)
Storage	32 GB microSD (Class 10/A2)	128 GB+ NVMe SSD (Pi 5) or USB SSD (Pi 4)
Power supply	Official 5V/3A USB-C (Pi 4)	Official 27W USB-C (Pi 5)
Case	Any passive case	Case with heatsink or active fan
Network	Wi-Fi (built-in)	Ethernet (strongly recommended for reliability)
USB dongle	None	Zigbee coordinator (Sonoff ZBDongle-P/E)

Pi 4 vs Pi 5: The Pi 5 is significantly faster (2-3x), has a native PCIe/NVMe slot (via HAT), and handles Home Assistant’s growing demands better. The Pi 4 (4 GB) works fine for a typical smart home with 50-100 devices. The Pi 4 (2 GB) is the absolute minimum — expect slowness with many integrations.

Do not use a Pi 3 or Pi Zero 2 W. Home Assistant has outgrown these. You will hit out-of-memory errors with even a moderate setup.

SSD Boot (Strongly Recommended)

SD cards fail. It is not a question of if, but when. SD cards are not designed for the constant small writes that Home Assistant’s database generates. An SSD extends the life of your setup from months to years.

Pi 5 with NVMe SSD: The Pi 5 has a PCIe connector. With the official Raspberry Pi M.2 HAT or a third-party NVMe base board, you can boot directly from NVMe. This is the best storage option — fast, reliable, no USB adapter needed.

1. Attach the NVMe HAT and insert an M.2 SSD
2. Update the Pi 5 bootloader to enable NVMe boot (it is enabled by default on recent firmware)
3. Flash HAOS or Raspberry Pi OS directly to the NVMe SSD

Pi 4 with USB SSD: The Pi 4 supports USB boot natively (enabled in bootloader since September 2020). Use any USB 3.0 SATA or NVMe enclosure with an SSD.

1. Update the Pi 4 bootloader: sudo rpi-eeprom-update -a
2. Flash HAOS or Raspberry Pi OS to the USB SSD using the Raspberry Pi Imager
3. Remove the SD card and boot from USB

A 128 GB SATA SSD in a USB 3.0 enclosure costs under $20 and eliminates SD card failures entirely.

Method 1: HAOS Installation (Recommended)

HAOS is a purpose-built Linux distribution that runs Home Assistant with the full Supervisor. You get the Add-on Store, managed backups, automatic updates, and the complete Home Assistant experience.

Flash the Image

1. Download the Raspberry Pi Imager on your computer
2. Insert your SD card or USB SSD
3. In the Imager:
   • Click Choose OS > Other specific-purpose OS > Home assistants and home automation > Home Assistant
   • Select the image matching your Pi model (Pi 4 or Pi 5, 64-bit)
   • Choose your target storage device
   • Click Write

Alternatively, download the HAOS image directly from the Home Assistant installation page and flash it with balenaEtcher.

First Boot

1. Insert the storage device into the Pi and connect Ethernet (recommended) or prepare for Wi-Fi setup
2. Power on the Pi
3. Wait 5-10 minutes for HAOS to initialize on first boot — it downloads and installs the latest Home Assistant Core version
4. Access the UI at http://homeassistant.local:8123 from a device on the same network

If homeassistant.local does not resolve, find the Pi’s IP address from your router’s DHCP lease table and access http://<pi-ip>:8123.

5. Complete the onboarding wizard: create an admin account, set your location, configure timezone and units

Wi-Fi Configuration (Headless)

If you cannot use Ethernet and need Wi-Fi from first boot:

1. After flashing, open the boot partition of the SD card/SSD on your computer
2. Create a folder called CONFIG/network/
3. Create a file called my-network inside it with:

[connection]
id=my-network
type=wifi

[wifi]
mode=infrastructure
ssid=YOUR_WIFI_SSID

[wifi-security]
auth-alg=open
key-mgmt=wpa-psk
psk=YOUR_WIFI_PASSWORD

[ipv4]
method=auto

[ipv6]
method=auto

Replace YOUR_WIFI_SSID and YOUR_WIFI_PASSWORD with your Wi-Fi credentials. Eject the drive, insert it in the Pi, and boot.

Installing Add-ons

HAOS gives you the Add-on Store — the main reason to choose this installation method. Essential add-ons:

• Mosquitto broker — MQTT broker for Zigbee2MQTT, Tasmota, and ESPHome devices
• Zigbee2MQTT — Zigbee device support (alternative to the built-in ZHA integration)
• File editor — Edit configuration.yaml and other config files from the browser
• Terminal & SSH — SSH access to the HAOS command line
• Samba share — Access Home Assistant config files from your computer’s file manager

Install add-ons from Settings > Add-ons > Add-on Store.

Method 2: Docker Installation

Use this if you already run Raspberry Pi OS and want Home Assistant alongside other services.

Install Docker on Raspberry Pi OS

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

Log out and back in.

Docker Compose Configuration

Create the directory structure:

sudo mkdir -p /opt/homeassistant/config

Create /opt/homeassistant/docker-compose.yml:

services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:2026.3.1
    volumes:
      - /opt/homeassistant/config:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0   # Zigbee/Z-Wave dongle (adjust path)
      - /dev/gpiomem:/dev/gpiomem   # GPIO access for sensors
    environment:
      - TZ=America/New_York
    restart: unless-stopped
    privileged: true
    network_mode: host

Start it:

cd /opt/homeassistant
docker compose up -d

Access the UI at http://<pi-ip>:8123.

GPIO Access

The Raspberry Pi’s GPIO pins can connect directly to sensors, relays, LEDs, and buttons. To use GPIO from Home Assistant’s Docker container:

• The privileged: true flag grants access to all host devices including GPIO
• Alternatively, map the specific device: devices: ["/dev/gpiomem:/dev/gpiomem"]
• Install the rpi_gpio integration in Home Assistant to read and control GPIO pins

GPIO is primarily useful for:

• DHT11/DHT22 temperature and humidity sensors
• PIR motion sensors
• Relay modules for controlling lights or appliances
• Button inputs for physical automations

For most smart home devices, Zigbee or Wi-Fi is a better protocol than GPIO. Use GPIO for custom hardware projects or when you need direct sensor connections without a wireless protocol.

USB Device Passthrough

Both HAOS and Docker methods support USB Zigbee and Z-Wave dongles. The Pi’s USB ports connect directly to the SoC without hub overhead.

For HAOS: Plug in the dongle before or after boot. HAOS detects it automatically. Configure ZHA or Zigbee2MQTT through the UI — the device path (usually /dev/ttyUSB0 or /dev/ttyACM0) is auto-discovered.

For Docker: Map the device path in docker-compose.yml:

devices:
  - /dev/ttyUSB0:/dev/ttyUSB0

Find the correct path:

ls -la /dev/ttyUSB* /dev/ttyACM*

If you have multiple USB serial devices, use udev rules for stable paths. See the Ubuntu guide for udev rule setup — the same approach works on Raspberry Pi OS.

Pi 4 USB port note: The two USB 3.0 ports (blue) share bandwidth with the Ethernet port over a single USB 3.0 bus. For Zigbee/Z-Wave dongles (which are low-bandwidth serial devices), use the USB 2.0 ports (black) and reserve the USB 3.0 ports for SSD and other high-bandwidth devices.

Platform-Specific Tips

• Power supply matters. Under-voltage causes random crashes, SD card corruption, and USB device disconnects. Use the official Raspberry Pi power supply. The lightning bolt icon in the Pi’s system tray (or dmesg | grep voltage) indicates under-voltage. A powered USB hub helps if you have multiple USB devices drawing power.
• Passive cooling is usually sufficient. Home Assistant’s CPU usage on Pi is low (~5-15% idle). A heatsink case (like the Flirc) keeps temperatures under 60C. Active fans are only necessary if you also run compute-heavy workloads.
• SD card wear monitoring. If you must use an SD card, monitor its health. HAOS shows storage health in Settings > System > Hardware. On Raspberry Pi OS, install smartmontools or check /sys/block/mmcblk0/stat for error counts. Replace the SD card annually as a preventive measure.
• Ethernet over Wi-Fi. Wi-Fi adds latency and drops connections under load. For a home automation hub that everything depends on, use Ethernet. If Ethernet is not possible, at least use 5 GHz Wi-Fi.
• Overclock the Pi 4 cautiously. Setting over_voltage=6 and arm_freq=2000 in /boot/config.txt improves Home Assistant responsiveness on the Pi 4, but requires active cooling and a good power supply. The Pi 5 runs fast enough at stock clocks.
• 64-bit OS. Always use the 64-bit version of HAOS or Raspberry Pi OS. Home Assistant benefits from the larger address space, especially with many integrations.

Troubleshooting

Home Assistant Extremely Slow on Pi

Symptom: The UI takes 10+ seconds to load. Automations have noticeable delay. Everything feels sluggish.

Fix: Check these in order:

1. SD card bottleneck. Run ioping -c 10 / and check latency. If average read latency is above 5ms, your SD card is the bottleneck. Switch to an SSD.
2. Insufficient RAM. Run free -h. If available memory is under 200 MB, you have too many integrations for your RAM. Unload unused integrations or upgrade to a Pi with more RAM.
3. Database size. Check /config/home-assistant_v2.db size. If it is over 1 GB, configure the recorder to limit retention:

   recorder:
     purge_keep_days: 5
     commit_interval: 10

4. Too many entities. Each entity consumes memory and CPU for state tracking. A Pi 4 (2 GB) handles ~200 entities comfortably. Beyond 500, consider a Pi 5 or a mini PC.

Zigbee Dongle Disconnects Randomly

Symptom: Zigbee devices go unavailable intermittently. The dongle disappears from /dev/ttyUSB0 and reappears.

Fix: This is almost always a power issue on Pi:

1. Check for under-voltage: dmesg | grep -i voltage
2. Use the official power supply
3. Move the Zigbee dongle to a USB 2.0 port (black) — USB 3.0 radio frequency interference can disrupt Zigbee’s 2.4 GHz signal
4. Use a short USB extension cable (10-15 cm) to move the dongle away from the Pi’s board-level RF noise

Boot Fails After HAOS Update

Symptom: Pi does not boot after a Home Assistant OS update. Screen shows errors or stays blank.

Fix:

1. Wait 10 minutes — some HAOS updates apply filesystem migrations at boot
2. If still stuck, pull the SD card/SSD and mount it on another computer. Check the hassos-data partition for the backup/ folder — your backups may be recoverable
3. Reflash HAOS and restore from a backup during onboarding (it prompts for backup restore)
4. To prevent: always create a backup before major HAOS updates (Settings > System > Backups > Create Backup)

Cannot Access homeassistant.local

Symptom: Browser shows “This site can’t be reached” for http://homeassistant.local:8123.

Fix: The .local hostname relies on mDNS, which not all routers or operating systems support reliably.

1. Find the Pi’s IP from your router’s DHCP lease table or connected devices list
2. Access http://<pi-ip>:8123 directly
3. Set a DHCP reservation for the Pi so the IP is stable
4. On Windows, mDNS may require Bonjour — install Bonjour Print Services or use the IP directly

GPIO Permission Denied (Docker)

Symptom: GPIO integration fails with permission errors in Docker.

Fix: Either use privileged: true (grants all device access) or map the specific GPIO device:

devices:
  - /dev/gpiomem:/dev/gpiomem
group_add:
  - "997"  # gpio group GID — check with: getent group gpio

On Raspberry Pi OS, the gpio group has access to /dev/gpiomem. Find the GID with getent group gpio and add it to group_add.

Related

• How to Self-Host Home Assistant with Docker
• Install Home Assistant on Ubuntu
• Home Assistant on Proxmox VE
• Best Self-Hosted Home Automation
• Home Assistant vs OpenHAB
• Replace Google Home
• Docker Compose Basics
• Getting Started with Self-Hosting
• Backup Strategy