Home Assistant is free, open source, and runs on almost anything. The tricky part? Choosing how to install it. There are four official methods, each with different trade-offs. This guide breaks down every option, tells you which one to pick, and walks you through the setup step by step.
Jump to a section
If you're new to Home Assistant or just want things to work, go with Home Assistant OS. It's the recommended method, gives you the full feature set, and is what 90% of users run. Here's the quick decision tree:
Recommended
Dedicated machine running only HA. Full feature set: add-ons, backups, updates, Supervisor. Flash it to an SD card or SSD and boot.
Best for: Most people. Beginners. Dedicated Pi or mini PC.
Advanced
Run HA as a Docker container alongside other services. No built-in add-on store, but full control over your system.
Best for: Existing server. Docker users. Multi-service setups.
Expert
Full HA experience (add-ons, Supervisor) on your own Debian install. You manage the OS, HA manages itself.
Best for: Linux pros who want add-ons plus OS control.
Developer
Python virtual environment install. Manual everything. No Supervisor, no add-ons, no GUI installer.
Best for: Contributors. Python devs. Testing only.
Here's what you get (and what you give up) with each method. The "full experience" means add-ons, Supervisor dashboard, automatic backups, and one-click updates.
| Feature | HA OS | Container | Supervised | Core |
|---|---|---|---|---|
| Add-on Store | ✅ | ❌ | ✅ | ❌ |
| Supervisor | ✅ | ❌ | ✅ | ❌ |
| Automatic Backups | ✅ | Manual | ✅ | Manual |
| One-Click Updates | ✅ | Docker pull | ✅ | pip install |
| OS Control | Limited | Full | Full | Full |
| Run Other Software | Add-ons only | Anything | Anything | Anything |
| Difficulty | Easy | Medium | Hard | Expert |
| Setup Time | 15 min | 30 min | 45 min | 60+ min |
This is the official, recommended way to run Home Assistant. You flash an image to your storage device, boot up, and you're done. The operating system is purpose-built for HA, so everything just works.
Step 1: Download the image
Go to home-assistant.io/installation and download the correct image for your hardware. For Raspberry Pi 5, pick the 64-bit image. For a generic x86-64 PC or NUC, pick the generic x86-64 image.
Step 2: Flash the image
Open Balena Etcher (or Raspberry Pi Imager). Select the downloaded image, choose your SD card or SSD, and click "Flash." This takes 3 to 5 minutes. Do not remove the card until it finishes verifying.
Step 3: Boot and wait
Insert the card (or connect the SSD), plug in ethernet, and power on. Home Assistant needs a few minutes on first boot to download and install the latest version. Don't touch anything for about 5 minutes.
Step 4: Open the dashboard
Open a browser and go to http://homeassistant.local:8123. If that doesn't work, try http://[your-device-ip]:8123. You'll see the onboarding screen.
Step 5: Create your account
Set up your name, username, and password. This is your admin account. Choose your location (for weather and sunrise/sunset automations), and let HA auto-discover devices on your network.
Pro tip: Use an SSD instead of an SD card
SD cards wear out and are slow. For Raspberry Pi 4/5, use a USB SSD adapter with any 2.5" SATA SSD. For the Pi 5, you can use an NVMe hat. The difference in speed and reliability is night and day. A 128GB SSD costs about the same as a good SD card.
Already running a home server with Docker? This method lets you add Home Assistant as another container. You keep full control of your OS and can run anything else alongside it. The trade-off: no built-in add-on store. You'll set up companion services (like Mosquitto, Z2M, or Node-RED) as separate containers.
version: '3'
services:
homeassistant:
container_name: homeassistant
image: ghcr.io/home-assistant/home-assistant:stable
volumes:
- ./config:/config
- /etc/localtime:/etc/localtime:ro
- /run/dbus:/run/dbus:ro
restart: unless-stopped
privileged: true
network_mode: hostSave this as docker-compose.yml, then run docker compose up -d. Home Assistant will be available at port 8123.
devices: - /dev/ttyUSB0:/dev/ttyUSB0 to your compose file./run/dbus mount handles this).docker compose pull && docker compose up -dFor a deeper look at Docker setup, companion containers, and troubleshooting, check our complete Docker guide.
This is the "best of both worlds" option, but it comes with strings attached. You get the full HA experience (add-ons, Supervisor, automatic backups) while keeping complete control of the underlying OS. The catch: it's only officially supported on Debian 12, and you need to follow a specific setup process.
# Install dependencies
sudo apt install -y apparmor jq wget curl \
udisks2 libglib2.0-bin network-manager \
dbus systemd-journal-remote
# Install Docker CE
curl -fsSL https://get.docker.com | sh
# Install OS Agent
wget https://github.com/home-assistant/os-agent/releases/latest/download/os-agent_linux_x86_64.deb
sudo dpkg -i os-agent_linux_x86_64.deb
# Install Supervised
wget https://github.com/home-assistant/supervised-installer/releases/latest/download/homeassistant-supervised.deb
sudo dpkg -i homeassistant-supervised.deb⚠️ Warning: Supervised is opinionated
If you deviate from the supported config (wrong OS, wrong Docker version, conflicting software), the Supervisor will show warnings and may mark your installation as "unsupported." This doesn't break anything, but you won't get help from the HA team if something goes wrong.
This is the barebones, manual installation. You install Python, create a virtual environment, and run Home Assistant directly. No Supervisor, no add-ons, no automatic updates. You manage everything yourself.
This method is mainly for developers contributing to Home Assistant or people who want to deeply understand how it works. For actual daily use, pick one of the other three methods.
# Install Python 3.12+ and dependencies
sudo apt install -y python3 python3-dev python3-venv \
python3-pip bluez libffi-dev libssl-dev libjpeg-dev \
zlib1g-dev autoconf build-essential
# Create a user and virtual environment
sudo useradd -rm homeassistant
sudo mkdir /srv/homeassistant
sudo chown homeassistant:homeassistant /srv/homeassistant
sudo -u homeassistant -H -s
cd /srv/homeassistant
python3 -m venv .
source bin/activate
# Install Home Assistant
pip3 install homeassistant
hassFirst run takes a while as it downloads and compiles dependencies. After that, access it at http://localhost:8123.
Home Assistant runs on surprisingly modest hardware. Here's what works at different budget levels.
Budget: Under $50
Still perfectly capable for a basic smart home. Pair it with a USB SSD for reliability. Handles 20 to 30 devices without breaking a sweat.
Best for: Getting started on a budget
Sweet spot
The Pi 5 is significantly faster than the Pi 4. The Home Assistant Green ($99) comes pre-loaded and ready to go. Both handle 50+ devices easily.
Best for: Most users. Great performance per dollar.
Power user
Fanless, low power (10W), and much faster than any Pi. 8 or 16GB RAM lets you run Frigate with AI object detection, multiple cameras, and dozens of add-ons.
Best for: 100+ devices, cameras, Frigate, heavy automations
What about a VM on your existing PC or NAS?
Running HAOS as a virtual machine on Proxmox, VirtualBox, or a Synology NAS works great. You get the full HA OS experience. Just make sure to pass through USB devices (for Zigbee/Z-Wave) and allocate at least 2GB RAM and 32GB disk. The official HA site has VM images ready to download for QCOW2, VMDK, VDI, and OVA.
Home Assistant is running. Now what? Here's what to do in your first session to get the most out of it.
The Home Assistant Community Store gives you access to thousands of custom integrations, themes, and dashboard cards. You install it separately, but most people add it within minutes. Takes 2 minutes. See our add-ons guide for instructions.
Go to Settings, then Devices & Services. Home Assistant auto-discovers many devices. For Zigbee or Z-Wave, you'll need a coordinator dongle. Check our Zigbee guide or Z-Wave guide to get started.
Before you spend hours configuring things, set up automatic backups. Nothing is worse than losing your setup to a corrupted SD card. Our backup guide covers automatic backups to Google Drive and other cloud storage.
The Home Assistant Companion app (iOS and Android) gives you push notifications, location tracking for presence detection, and quick access to your dashboard. It also exposes your phone's sensors (battery, steps, Wi-Fi) to HA.
Start simple. Turn on a light when you get home. Send a notification when a door opens. The visual automation editor makes this easy, no code needed. Check our automations guide for 30 ideas to get you started.
mDNS doesn't work on all networks. Try finding the IP address directly: check your router's DHCP list, or run arp -a from your computer. Access HA at http://[IP]:8123 instead.
First boot can take up to 20 minutes on slower hardware (especially Pi 3/4 with SD cards). If it's been over 20 minutes, check if the device has internet access. HA needs to download the latest version on first boot.
Older Pi 4 units need a bootloader update to boot from USB. Update the EEPROM first using a regular SD card, then switch to USB boot. Pi 5 supports USB boot out of the box.
Add your USB device to the compose file under devices. Run ls /dev/ttyUSB* or ls /dev/ttyACM* to find the right path. Restart the container after adding it.
Run our free scan to see which of your current devices work with Home Assistant. We'll check compatibility, suggest a migration path, and tell you what to keep and what to replace.
Scan Your Devices FreeFor most people, Home Assistant OS on a Raspberry Pi 5, Home Assistant Green, or a mini PC is the best option. It gives you the full experience including add-ons, backups, and automatic updates. Only choose Docker (Container) if you already run other services on the same machine and know your way around containers.
Not directly. Home Assistant OS runs on Linux. On Windows, you can use a virtual machine (VirtualBox or Hyper-V) to run HAOS, or install Docker Desktop and run Home Assistant Container. The VM approach gives you the full experience including add-ons. Docker works but you will need to set up add-ons as separate containers.
At minimum: a Raspberry Pi 4 (2GB) or any x86 mini PC with 2GB RAM and 32GB storage. For a comfortable experience, a Raspberry Pi 5 (4GB) or an Intel N100 mini PC with 4GB RAM and 128GB SSD is ideal. If you plan to run Frigate for camera AI, you will want at least 8GB RAM and a Coral TPU.
Yes, Home Assistant is completely free and open source. The software costs nothing. You only pay for the hardware to run it on. There is an optional Nabu Casa subscription (5 dollars per month) for easy remote access and voice assistants, but it is not required.
The actual installation takes about 15 to 30 minutes. Flashing the SD card or SSD is 5 to 10 minutes, first boot and setup is another 10 to 15 minutes. After that, you can start adding devices right away. A basic smart home setup with a few lights and sensors takes another hour or two.
A Raspberry Pi 5 is perfect for most setups with up to 50 devices. If you plan to run camera AI (Frigate), multiple add-ons, or have 100+ devices, an Intel N100 mini PC will give you more headroom. The Pi costs less up front, but the mini PC is more powerful per watt.
Yes, but it requires migrating your configuration. The easiest path: create a full backup in your current install, then restore it on the new one. Going from Container to OS (or vice versa) means you'll need to manually move your config directory. Going from OS to Supervised keeps the full experience intact.
Best first devices, hub comparison, and a weekend setup timeline.
Companion containers, networking, USB passthrough, and performance tips.
Coordinators, ZHA vs Z2M, best devices, and mesh tips.
Ideas and YAML for lighting, climate, security, and presence.
Automatic backups, Google Drive, Docker scripts, and the 3-2-1 rule.
Essential add-ons for connectivity, automation, security, and media.