Which Home Assistant install methods the official docs support on a Raspberry Pi, the Imager steps, first boot, three first integrations, and how to tell local control from cloud.
Settle the install method before touching an SD card, because it decides what the finished system can do. Home Assistant’s own installation page lists two routes for a Raspberry Pi: Home Assistant Operating System, which takes over the board, and Home Assistant Container, which runs as a program on an operating system you already manage.
The rest of this guide stays inside what the official pages state: which boards each route supports, the Raspberry Pi Imager steps, the first-boot sequence, three integrations worth adding first, and how to tell local control from cloud dependence. Where the documentation is silent, this guide is too.
Which install method fits a Raspberry Pi?
| Method | Raspberry Pi models listed | What the docs say |
|---|---|---|
| Home Assistant OS | Pi 4 or Pi 5, minimum 2 GB RAM | “The recommended installation type.” Described as a great option if you already have a Raspberry Pi. |
| Home Assistant Container | Pi 3, 4 or 5 | Described as “a low-cost DIY solution.” No access to apps, and no out-of-the-box support for Thread or Z-Wave. |
The pages also describe Home Assistant Green, which “comes with Home Assistant Operating System already installed,” and HA OS on Odroid and x86-64 hardware. No deprecation notice appears on the installation page. The Linux page defines Container as “a standalone container-based installation of Home Assistant Core,” and the pages fetched for this guide do not discuss any other method, so none is described here (Linux install page).
Opinion, informed by that table: unless the plan involves running other containers on the same Pi, the recommended HA OS route removes the most decisions. Container suits someone who already has Docker running and wants Home Assistant as one service among several.
What to gather
- A Raspberry Pi 5 or Pi 4 with at least 2 GB of RAM for HA OS.
- A microSD card of at least 32 GB. The docs recommend an Application Class 2 card, labeled A2, for better performance hosting applications.
- A proper power supply. Do not power the Pi from a computer’s USB port.
- An Ethernet cable. The page says it is required for installation; Wi-Fi works afterward, though Ethernet is more reliable.
Those are the documented requirements (Raspberry Pi install page). For a look at one packaged Pi 5 starter kit, see the CanaKit Raspberry Pi 5 kit review; for turning a Pi into a general home server, see the Raspberry Pi home server guide. Specific boards and cards are left unlinked here because their product listings could not be verified.
Install Home Assistant OS with Raspberry Pi Imager
- Install Raspberry Pi Imager from raspberrypi.com/software.
- Open it and click OS.
- Go to Other specific-purpose OS, then Home automation, and select Home Assistant.
- Choose the image for the board, RPi 4 or RPi 5.
- Insert the SD card and select it as storage. The docs warn that the contents of the card will be overwritten.
- Click Next, choose Write, and wait for it to finish.
- Click Finish and eject the card.
If Imager is not available on a platform, the page suggests downloading the image directly and writing it with a tool such as Balena Etcher.
First boot and onboarding
Put the card in the Pi, connect Ethernet so the board is on the same network as your computer with internet access, and connect power. Then open this address from a browser on the computer:
http://homeassistant.localIf that does not load, the page offers homeassistant.local:8123, homeassistant:8123, or http://X.X.X.X:8123 with the Pi’s IP address. On a Pi 4 or 5 the page should be available within a minute; if it is still missing after five minutes, the docs suggest reflashing the card, possibly a different one, and attaching a monitor over HDMI to read console output.
First visit starts onboarding, which begins by downloading the latest version, roughly 700 MB (onboarding docs). Then:
- Create the owner account, an administrator. The docs warn that these credentials cannot be recovered, so store them somewhere safe. A backup from a previous installation can be restored here instead.
- Enter the home’s location, which sets time zone, unit system and currency and creates a home zone with a default 100 m radius.
- Choose what anonymized data to share. Sharing is disabled by default.
- Arrive at the default dashboard.
The Container route
Container needs Docker Engine 23.0.0 or later; Docker Desktop is not supported. The Linux page supplies a docker run example, reproduced below with the placeholders left in place (Linux install page). Replace the time zone and the config path, and check the page for the current form before running it.
docker run -d \
--name homeassistant \
--restart=unless-stopped \
--privileged \
-e TZ=MY_TIME_ZONE \
-v /PATH_TO_YOUR_CONFIG:/config \
-v /run/dbus:/run/dbus:ro \
--network=host \
ghcr.io/home-assistant/home-assistant:stableThe D-Bus volume is marked optional and is needed for Bluetooth. The page also provides a Docker Compose version with the same settings. Remember the trade: Container installs do not have access to apps.
First integrations worth adding
Integrations are how Home Assistant talks to devices. Three common starting points, each with a different flavor.
Philips Hue
Home Assistant can auto-discover Hue bridges. A discovered bridge appears as “Discovered” and can be set up immediately; if it is not found, add it manually under Settings, Devices & services, Add Integration, Philips Hue. Its IoT class is Local Push. V2 (square) bridges push state changes instantly over a local event stream, while V1 (round) bridges are polled on an interval (Hue integration).
Matter
The Matter integration controls Matter devices on a local Wi-Fi or Thread network and is also Local Push. Submitting the integration under Settings, Devices & services installs the official Matter Server app. Thread devices need a Thread border router near the device and the phone; the docs name a Nest Hub (2nd Gen), HomePod mini, Apple TV 4K, or Home Assistant with the OpenThread Border Router app. Wi-Fi devices want the phone on the same 2.4 GHz network the device will use (Matter integration). Pairing happens from the Companion app with Bluetooth on and the phone held close to the device: the page lists Android 8.1 as the minimum (12 or higher recommended) and iOS 16 or higher, though its troubleshooting section cites 16.4, so check the latest guidance. The official Matter Server app is not supported on 32-bit platforms. Before adding Thread gear, the Thread and Matter network audit is a useful way to see what the network already contains, and the mesh Wi-Fi guide helps if coverage is patchy.
MQTT
MQTT is a machine-to-machine messaging protocol, and the integration connects Home Assistant to a broker. The broker must support MQTT version 5; Mosquitto is the recommended one, and ActiveMQ and the RabbitMQ MQTT plugin are not supported. Its IoT class is Local Push (MQTT integration).
Local control versus cloud
Every integration page carries an IoT class, and the classification is the quickest way to see where control happens. The definitions come from a 2016 Home Assistant post that is still the reference for the labels (Classifying the Internet of Things).
| IoT class | Meaning |
|---|---|
| Local Push | Direct communication with the device; Home Assistant is notified as soon as a new state is available. |
| Local Polling | Direct communication with the device, but Home Assistant has to check repeatedly, so changes may show up later. |
| Cloud Polling | Goes through the cloud and requires an active internet connection; Home Assistant checks periodically. |
| Cloud Push | Goes through the cloud; the cloud notifies Home Assistant as soon as a new state is available. |
| Assumed State | State cannot be read, so Home Assistant estimates it from the last command. |
The integrations directory has an IoT Class filter, so choosing devices that list a local class is a practical way to keep working lights and switches when the internet is down. The same logic explains the Hue note above: a V1 bridge is polled, so a state change may take a moment to show up in Home Assistant, while a V2 bridge reports it immediately. The reasoning in the first sentence is an inference from the definitions, not a tested outage claim.
Sources
