How to Install Home Assistant on Raspberry Pi Using Docker

Home Assistant is an open-source home automation platform that lets you control and automate smart devices from a single dashboard. Running it on a Raspberry Pi with Docker gives you an always-on, low-power smart home hub that is easy to maintain and update.

Prerequisites

Before you begin, make sure you have:

A Raspberry Pi 4 or 5 (2 GB RAM minimum, 4 GB recommended)
Raspberry Pi OS (64-bit) installed and up to date
Docker and Docker Compose installed (see our Docker setup guide)
SSH access or a keyboard and monitor connected to the Pi

Update your system first:

Bash

sudo apt update && sudo apt upgrade -y

Step 1: Create the Project Directory

Create a directory to hold the Home Assistant configuration and compose file:

Bash

mkdir -p ~/home-assistant
cd ~/home-assistant

Step 2: Create the Docker Compose File

Create a docker-compose.yml file in the project directory:

YAML

services:
  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:stable
    container_name: homeassistant
    restart: unless-stopped
    privileged: true
    network_mode: host
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    environment:
      - TZ=America/New_York

A few notes on this configuration:

network_mode: host gives Home Assistant direct access to the host network, which is required for device discovery protocols like mDNS and SSDP.
privileged: true allows access to hardware devices such as Zigbee or Z-Wave USB dongles.
/run/dbus is mounted so that Home Assistant can interact with the host D-Bus, which is needed for Bluetooth support.

Step 3: Start the Container

Launch Home Assistant with Docker Compose:

Bash

cd ~/home-assistant
docker compose up -d

Check that the container is running:

Bash

docker ps

You should see the homeassistant container listed with a status of "Up".

Step 4: Access the Setup Wizard

Open a browser and navigate to:

Code

http://<your-pi-ip>:8123

Replace <your-pi-ip> with the actual IP address of your Raspberry Pi. You can find it by running hostname -I on the Pi.

The onboarding wizard will guide you through:

Creating your admin account
Setting your home name and location
Selecting your time zone and unit system
Discovering devices already on your network

Step 5: Install Integrations

After the initial setup, navigate to Settings > Devices & Services to add integrations. Home Assistant supports thousands of devices out of the box, including:

Philips Hue -- smart lights and accessories
Google Cast -- Chromecast and Google Home speakers
TP-Link Kasa / Tapo -- smart plugs and switches
Shelly -- Wi-Fi-based relays and sensors
Zigbee / Z-Wave -- with a USB coordinator like the Sonoff Zigbee dongle

Many integrations are auto-discovered if you used network_mode: host.

Step 6: Create Your First Automation

Go to Settings > Automations & Scenes > Create Automation. A simple example: turn on a light at sunset.

Set the trigger to Sun > Sunset
Set the action to Call Service > light.turn_on
Select the target light entity
Save the automation

Home Assistant also supports YAML-based automations in the config/automations.yaml file for more advanced logic.

Updating Home Assistant

To pull the latest image and restart the container:

Bash

cd ~/home-assistant
docker compose pull
docker compose up -d

Home Assistant releases updates frequently, so check the release notes before upgrading.

Troubleshooting

Cannot access port 8123: Make sure no firewall is blocking the port. Run sudo ufw allow 8123 if UFW is enabled.
Devices not discovered: Confirm network_mode: host is set. Bridge mode will prevent discovery protocols from working.
Container keeps restarting: Check logs with docker logs homeassistant for error details.
Bluetooth not working: Ensure /run/dbus is mounted and that the dbus service is running on the host with sudo systemctl status dbus.
Slow performance: A Raspberry Pi 3 may struggle. Use a Pi 4 or 5 with at least 2 GB RAM and a fast microSD card or USB SSD.

Conclusion

Home Assistant on a Raspberry Pi is one of the most practical self-hosted projects you can run. With Docker keeping the installation clean and portable, you get a powerful home automation hub that is easy to back up, restore, and update. Start with a few integrations and build from there -- the possibilities are nearly endless.