Getting Started With Home Assistant on Raspberry Pi (2 Ways)

Home Assistant is one of the most useful things you can run on a Raspberry Pi. It lets you control all your smart devices from one place, with tons of customization options. I’ve set it up more times than I can count, so here’s a clear, step-by-step guide to help you do it easily too.

Home Assistant is available as an installable image for the Raspberry Pi that can be flashed to an SD card as a complete system. It’s also available as a Docker container, making it possible to use Home Assistant alongside other services on the same system.

I’ll go over both of these installation methods, so just pick the one that works best for your setup. Then, I’ll give you a few tips to get you started the right way, no matter which installation method you picked. Let’s do this!

If you’re new to Raspberry Pi or Linux, I’ve got something that can help you right away!
Download my free Linux commands cheat sheet – it’s a quick reference guide with all the essential commands you’ll need to get things done on your Raspberry Pi. Click here to get it for free!

Home Assistant Installation with Dedicated Image

If your Raspberry Pi will be solely dedicated to Home Assistant, use this installation method. It’ll be much simpler in the long run.

You’ll be performing the same steps as you do for flashing any operating system image on your Pi. Here’s an overview of how to install Home Assistant on Raspberry Pi:

• Flash Home Assistant onto an SD card with Raspberry Pi Imager.
• Insert the SD card into the Raspberry Pi.
• Boot into Home Assistant

I will explain each step in detail next.

Flash Home Assistant onto an SD card

Home Assistant officially supports the Raspberry Pi 5, 4B, and 3B, so it offers an image built for it.

Note: This method will install the 64-bit image of Home Assistant. It’s still possible to find a 32-bit image with some extra leg work, but support for it has reached end-of-life.

Here’s how to flash Home Assistant onto an SD card:

• Download and install Raspberry Pi Imager, if you don’t have it already.
  Raspberry Pi Imager is a free tool to easily install a new OS, copying the file from a system image to the SD card.
• Insert the SD card into your PC.
  You will probably need an SD/MicroSD card adapter.
  And if you don’t have an SD card reader in your PC, you can buy a USB adapter like this one. You’ll use it all the time with your Raspberry Pi, so it’s worth it to have one.
• Launch Raspberry Pi Imager, and make the following selections.
• Device – choose your Pi model.
• OS – Navigate to Other specific-purpose OS > Home Automation > Home Assistant, and select Home Assistant OS.
  
• Storage – point to your SD Card.
• Writing – click the “WRITE” button to begin the flashing process.

Imager will begin writing to your SD card. After a few minutes, it should be done, and you can eject the SD card from your computer.

First Boot with Home Assistant

You’re now ready to start Home Assistant for the first time. To make things easier, please plug your Raspberry Pi into a network cable before turning it on:

• Insert the SD card into your Raspberry Pi.
• Make sure everything else is plugged in (especially network & monitor).
• Power it on and wait a few minutes.

Home Assistant creates a web interface for you to manage everything, so there’s nothing you need to do on the monitor directly—except for taking note of the URL.

Just wait a bit to get the Home Assistant CLI to show up, and then you can jump down to the Getting Started with Home Assistant section (skip the Docker part of this tutorial).

Note: I recently had to set it up using Wi-Fi, and it wasn’t intuitive at all. Here’s what I did in case it helps you out. Start by opening the full CLI with:
login
And you can then use nmcli to configure the connection:
nmcli dev wifi connect 'YOUR-SSID' password 'YOUR-PASSWD'
Warning: the default keyboard layout is QWERTY and it seems there is no way to change that.

Home Assistant Installation with Docker

If you already have other services on your Pi and want to keep them running, use this method instead. Installing Home Assistant with Docker is a great choice if you already have Raspberry Pi OS (or another distribution) running and want to add it like it’s an additional application.

Update Your System

I’m testing this setup on the latest Raspberry Pi OS version available at the time of writing (Trixie 64-bit), but it should work on any Debian-like distribution. If you’re using other Linux systems like Manjaro or Arch, you’ll need to adapt some of these commands.

To avoid issues during installation, make sure your system is up-to-date first:
sudo apt update
sudo apt upgrade

If there are a lot of updated packages, a reboot is recommended before going further:
sudo reboot

Tip: Command lines can be a pain to memorize. I put the essential Linux commands on a printable cheat sheet so you don't have to keep googling them. You can grab the PDF here if you want to save some time.

Install Docker on Raspberry Pi

The official documentation doesn’t explain how to set up Docker on the Raspberry Pi, which is where you might get lost, so I’ll answer your questions here.

• The Docker package in the default repository for Raspberry Pi OS is outdated.
• The best way to install Docker on Raspberry Pi OS is to run this command:
  curl -sSL https://get.docker.com | sh
  

You don’t need to use sudo, the script will do it for you. Basically, this command will add a new repository to your APT sources, and install the packages from there. When it’s done, Docker will start its service automatically and print out the version.

If you are new to this, I recommend reading my complete guide about Docker on Raspberry Pi first. Just to make sure you understand what you’re doing here.

Create a Docker Container for Home Assistant

Now that Docker is set up on your system, you can follow the documentation and create a new container with Home Assistant.

Method #1: via Docker Command

Here’s the command syntax to launch Home Assistant with Docker via a command:

docker run -d \
--name homeassistant \
--privileged \
--restart=unless-stopped \
-e TZ=MY_TIME_ZONE \
-v /PATH_TO_YOUR_CONFIG:/config \
--network=host \
ghcr.io/home-assistant/home-assistant:stable

Yes, that is a long command, and you need to adjust it for your system:

• Replace MY_TIME_ZONE with your current timezone. The format is Country/City.
  For example: TZ=Europe/Paris (You might be able to find your timezone quickly by typing the command “timedatectl”)
• Replace PATH_TO_YOUR_CONFIG with the folder where you want to store the configuration files.

In my case, I just used this example:

docker run -d \
--name homeassistant \
--privileged \
--restart=unless-stopped \
-e TZ=Europe/Paris \
-v /home/pat/hass:/config \
--network=host \
ghcr.io/home-assistant/home-assistant:stable

Note: If you get this error: “docker: Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock,” make sure you followed our installation guide fully.

You can fix it by running this command, logging out, and logging back in again:
sudo usermod -aG docker $USER

After running this command, the container will start and the web interface will be available. You’ll learn how to access it in the Getting Started with Home Assistant section below.

Method #2: via Docker Compose

If you find it easier to manage containers via a persistent text file, you can launch Home Assistant via Docker Compose instead:

• Create a project folder for Home Assistant:
  mkdir ~/HA
cd ~/HA
• Inside that folder, create a compose.yaml file:
  nano compose.yaml
• Paste the following lines:

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

• Change these parts, if needed:
  • “Europe/Amsterdam” with your time zone.
  • “./:config” refers to the current directory. You can replace the “./” part with a different path if you want to store the files somewhere else.
• Save & exit (CTRL+X).
• Launch the Home Assistant container:
  docker compose up

Now the container will start and the web interface should be available. You’ll learn how to access it in the Getting Started with Home Assistant section below.

(If you want to learn more about how to use Docker Compose, check out our guide: The Easier Way to Run Docker on Raspberry Pi.)

Optional: Updating Home Assistant When Using Docker

Updating Home Assistant with the Docker installation method is a bit tricky. You can’t just run apt upgrade and hope that you’ll keep it up-to-date. After reading the documentation, the only way to update it seems to remove the container and create a new one with the new version.

Here is the command to run (in this order):
sudo docker pull ghcr.io/home-assistant/home-assistant:stable
sudo docker stop homeassistant
sudo docker rm homeassistant

Then, you can use the same command as during the installation to recreate the container. Make sure to use the same path for the configuration folder if you don’t want to start from scratch.

Getting Started with Home Assistant

Once Home Assistant installed, it’s now time to connect it to all your smart devices and start having fun with it!

Access the Web Interface

Whatever installation method you chose, Home Assistant will start a web interface on the port 8123 of your Raspberry Pi. You can generally access it with http://homeassistant.local:8123 or http://IP_ADDRESS:8123.

You can check this post on how to find your Raspberry Pi IP address if you don’t know it yet.

You should get a form, as seen on the above screenshot, asking you to create the first user account.

Then you will be asked a few questions to customize your setup:

• Give a name to your Home Assistant installation.
• Set your location, timezone, unit system, and currency.
• Check the boxes corresponding to the data collection you wish to share (or skip this screen).
• The wizard will then scan your network and offer to quickly add supported smart devices:
  
• Just click on the one you want to add, or click “Finish” to do this later.
  In my case, it detected most of the ones that were connected during the installation (lights, smart plugs and NAS).
• Adding each device may require additional steps. For example, for Philips Hue lights, you need to press the button on the hub to allow Home Assistant to control it, and then assign each light to a room.
• You can obviously click “More” to add additional integrations (like websites or things that has not been detected automatically), but I recommend doing this once in the full interface.

Once this onboarding wizard is complete, you should get access to the full interface, with a nice dashboard including the integrations you set up:

You can now use this interface to manage your smart devices. For example, I can switch off or on the kitchen light by clicking the corresponding button. But Home Assistant goes way further than that.

Add More Integrations

First, make sure to set up all your smart devices on this interface. You can use the Settings item in the left menu to add new ones:

• Click on Settings and then Devices & Services.
  
• You’ll get the same list as during the onboarding process, but you can also add new integrations.
• Home assistant is compatible with a lot of services related to home automation.
  Here are a few examples: weather websites, network devices (Unifi, Synology, …) , cloud services (Google, Apple, …), robots (vacuum), smart plugs (home, car, …), etc.
  You’ll get the full list when you click on “Add Integration”—it’s insane all of the things you can monitor and use in your automations.
• You’ll then get extra steps depending on the integration you want to add.
  For example, to connect to a weather API, you’ll generally need an API key (you can often get one for free, just by creating an account on their website).
  For a robot vacuum, you’ll probably need to press a button on it. Etc.

Try to add a few integrations. Home Assistant becomes an exciting project when you have many smart devices and can make them work together by creating some automation (ex: when I open the door, turn lights on in the living room and play my favorite song). But even with a few of them and addition web services, you can already build some nice dashboards.

Create a New Dashboard

By default, Home Assistant will create a basic dashboard called “Overview” and another one named “Energy.” But you can edit them, delete them or create new ones. Here’s how:

• Go to Settings > Dashboards.
• Click the + Add Dashboard button.
• Choose a title and an icon:
  
• Then click on the Dashboard you’ve created in the left menu to open it.
• You can now click in the top-right corner menu and choose “Edit Dashboard” to customize it.
• From there, you can do everything you want: add new cards, delete some, move the existing ones up and down, etc.
• For each card, there are many templates you can use to format the data differently (button, calendar, history graph, gauge, etc.).
  
• After choosing a template, you’ll need to pick the exact value you want to display on it.
  For example, in my Weather dashboard, I can choose to display the temperature, precipitation, UV index, etc.
  

You may think it’s complicated while reading this, but once you try, it’s pretty intuitive. So I’m sure you’ll understand everything quickly. Start with something you really want to have on your dashboard, and find the best way to display the value.

Create Your First Automation

Obviously, Home Assistant is not only a way to have nice dashboards and replace several apps with one. It’s also the most effective way to automate your home.

Automation is a process that will run automatically when a trigger is detected:

• If the inside temperature drop below 20 °C, turn on the heater.
• When motion is detected in the bedroom, turn on the wall light.
• If the wind is over 60 km/h, close the shutters.
• Etc.

Creating an automation is not complicated once you get the idea. Find something simple you want to try, and follow these steps to configure it:

• Go to Settings > Automation & Scenes.
• Click the + Create Automation button.
• Change the automation name to something you’ll remember.
  A one sentence telling exactly what it does is best.
• In the triggers part, set the device that will be used to start the automation.
• Then set the exact trigger sensor and value that will start the automation.
  For example, I tested with AccuWeather (a weather web service), and tell that when the cloud ceiling is below a certain threshold, it will start an automation to light on the house.
  But you can simply use the “Sun” trigger, and turn on the lights on sunset for example.
  
• You can add conditions in the next section if needed.
  Dumb example: don’t turn on the kitchen if the light is already on.
• Then, set the actions that should be triggered when the conditions are fulfilled.
  In my case: Turn on the kitchen light, for example.
  You may also tweak other settings like the brightness for lights, etc.

Try to create something simple first, and check if it’s working. Depending on the smart devices and integrations you set up, this will be more or less easy to test. The possibilities are endless, just try to think of something useful for your house.

Video

https://www.youtube.com/watch?v=dZFHyvY2Gp8

Final Thoughts

Overall, Home Assistant is one of the top tools for a Raspberry Pi smart home. The installation is pretty straightforward, and you can do almost anything with it. The interface is intuitive and only gets complicated if you try to build automations with multiple interconnected devices.

If you have smart devices, but find they are not that smart, and you still need to do many tasks manually, Home Assistant could be what’s missing in your home. It might save you money from having to buy dedicated devices to achieve what you want.

Try to install Home Assistant and find some ways to make it useful, such as these easy home automation projects. It’ll give you an excuse to spend more time on your Raspberry Pi :-).

Domoticz and HOOBS are alternatives to consider (click on the links to read my articles about these), but I think Home Assistant is my favorite currently.

If you are using Ubuntu on your Raspberry Pi, or even on your computer, you can check this other article to get more details for this distribution: Install Home Assistant on Ubuntu: A Step-by-step guide

Not getting the same result?

Even when you follow every step, small differences in OS version, hardware or config can change the outcome. Instead of wasting time guessing, get help from people who have already fixed the same kind of issue.

Ask your question now →

🔒 No risk. Cancel anytime.

• Get help on your exact issue
• Access step-by-step videos for tricky setups
• Browse the website without ads