To install Home Assistant in Portainer, you create a stack (Stacks, then Add stack, then Web editor), paste in the compose file Home Assistant publishes, and select Deploy the stack. That compose file pulls ghcr.io/home-assistant/home-assistant:stable and keeps your configuration in a folder on the host. It also runs the container with host networking, so Home Assistant answers on port 8123 directly and mDNS discovery can actually reach it.
As of October 2026 (Home Assistant 2026.10), Home Assistant Container is the only supported way to run Home Assistant in Docker, so every Home Assistant Portainer install is a Container install. It is not the method Home Assistant recommends for most people, though (and it isn’t the one I use), so it’s worth knowing what you give up first.
Home Assistant Container vs Home Assistant OS
Home Assistant OS is a full operating system rather than a container, so there’s no HAOS Portainer install. You run it on its own hardware or as a virtual machine, and what you get in Portainer is Home Assistant Container.
Home Assistant’s installation method comparison is fairly short. Automations, dashboards, integrations, blueprints and backups work in both. Container has no apps (called add-ons before 2026.2) and no one-click updates, because both come from the Supervisor, which Container doesn’t include. That also means Thread and Z-Wave, which Home Assistant runs through apps, have no out-of-the-box support on Container.
The other two Docker-based methods are gone. In May 2025, Home Assistant’s deprecation announcement said Home Assistant OS and Home Assistant Container would become the only supported installation methods, and support for Core and Supervised ended with release 2025.12. Existing Supervised installs still run, but issue reports for them are no longer accepted, so if you’d like Home Assistant in Docker, Container is how you do it.
On my own setup, I went the other way. When I set up Home Assistant on a Synology NAS in 2024, I skipped Docker and Container Manager and used a virtual machine instead. The main reason was the Home Assistant Supervisor, which the VM installs automatically, and in my opinion that’s the best way of running Home Assistant. You also get snapshots, so before testing something you can shut Home Assistant down, take a snapshot and start it back up. If anything goes wrong, you have a quick way back. Without the Supervisor, you’d be manually managing containers, dependencies, and updates.
I still run Home Assistant OS as a VM. I’ve restored my Home Assistant VM from a backup directly into Proxmox, and it came up and worked perfectly. If you’re starting from scratch, I’d point most people to a VM, either installing Home Assistant on Proxmox or installing Home Assistant on a Synology NAS.
With that said, Container makes sense when you already run a Docker host and want Home Assistant to be one more stack on it. You just have to be fine without apps and handle updates yourself. If that’s you, a Portainer Home Assistant stack is a simple way to do it.
The Home Assistant Portainer integration is the reverse direction, since it connects Home Assistant to a Portainer instance you already run and does not install anything. Running Portainer inside Home Assistant OS is different again: the community Portainer app (an add-on before 2026.2) was deprecated in 2021, and only third-party app repositories offer one now.
How to Install Home Assistant on Portainer
You’ll need Docker Engine 23.0 or later and Portainer running on a 64-bit Linux host first. If you don’t have Docker and Portainer set up yet, do that before anything else (or follow installing Portainer on a Raspberry Pi). A Raspberry Pi 3, 4 or 5 works as long as it’s running a 64-bit OS. It uses the same image as every other host, so the old Pi-specific image tags don’t apply anymore. The original Pi and the Pi 2 aren’t on that list, since Home Assistant stopped building for 32-bit systems with 2025.12.
1. Create a folder on the host for Home Assistant’s configuration. Everything Home Assistant stores lives in this folder, which is also what makes it easy to back up or move to another machine later.
sudo mkdir -p /opt/homeassistant/config
2. Log in to Portainer, select your environment (usually local), then select Stacks, and finally, Add stack.

3. Give the stack a name (homeassistant works), then select Web editor.
4. Paste the compose file below into the editor. It’s the one from Home Assistant’s own Container install docs, with the config path pointed at the folder from step 1 and a US time zone filled in.
services:
homeassistant:
container_name: homeassistant
image: "ghcr.io/home-assistant/home-assistant:stable"
volumes:
- /opt/homeassistant/config:/config
- /etc/localtime:/etc/localtime:ro
- /run/dbus:/run/dbus:ro
restart: unless-stopped
stop_grace_period: 60s
privileged: true
network_mode: host
environment:
TZ: America/Los_Angeles
Change the part before :/config if your folder lives somewhere else, and set TZ to your own time zone database name (America/New_York, America/Chicago, etc). Leave network_mode: host and privileged: true alone, and notice there’s no ports: section, which is on purpose (the next section explains why). The restart: unless-stopped line brings Home Assistant back after a reboot unless you stopped it yourself.

5. Select Deploy the stack. The first deploy has to pull the image, so give it a few minutes.

6. Open the IP address of your Docker host on port 8123 and continue with onboarding (create a new smart home, or restore a backup).
http://IP_ADDRESS:8123
If the page doesn’t load, newer Linux distributions restrict access by default, so open TCP port 8123 in the host’s firewall (on Ubuntu with ufw, that’s the command below).
sudo ufw allow 8123/tcp
Don’t forward that port on your router unless you mean to put Home Assistant on the internet. As always, security changes over time, so nothing here is guaranteed.
Once you’re in, installing HACS on Home Assistant is the usual next step, and the Docker method there runs from the same config folder you just created.
Why Home Assistant Needs Host Networking in Portainer
Home Assistant’s compose file uses network_mode: host and publishes no ports because mDNS discovery can’t reach a container on a Docker bridge network. In host mode, the container shares the host’s network stack, so Home Assistant answers on the host’s port 8123. If you add port mappings anyway, Docker ignores them and prints a warning.
When I first wrote this guide, I mapped host port 8123 to container port 8123 on that bridge network, which gets you the web interface but leaves Home Assistant on an isolated network. Home Assistant’s HomeKit docs spell out what that costs. The fix they give is either network_mode: host or an mDNS forwarder on the Docker host (avahi-daemon in reflector mode). Host networking is the simpler of the two, and it’s what Home Assistant documents for every Container install.
Host networking is also a Linux feature, and Home Assistant’s docs say Docker Desktop will not work at all, so the host here is a Linux machine, a Linux VM, or a Raspberry Pi.
Bluetooth, Zigbee and Z-Wave
Bluetooth needs BlueZ running on the host and the /run/dbus:/run/dbus:ro line, so leave it in if you plan to use the Bluetooth integration. A Zigbee stick used with ZHA has to be mapped into the container. Add a devices: section under homeassistant: with your stick’s path (ls /dev/serial/by-id/ lists its ID), then select Update the stack from the stack’s Editor tab and Update in the prompt.
devices:
- /dev/serial/by-id/YOUR_STICK_ID:/dev/ttyUSB0
When you add ZHA, choose /dev/ttyUSB0, the container’s side of that line.
Z-Wave is different on Container: the stick goes to a separate Z-Wave JS UI container, the setup Home Assistant’s Z-Wave docs recommend, and the Z-Wave integration connects to that.
How to Update Home Assistant in Portainer
To update Home Assistant in Portainer, you redeploy the stack on a freshly pulled image, because Container has no one-click updates. In my October 2026 comparison of Docker managers, Portainer’s Community Edition didn’t tell you when an image update was available (that’s a Business Edition feature). So in CE, you’re generally pulling and redeploying images yourself.
Before you update, create a backup with the Backup integration, keep the backup emergency kit Home Assistant gives you somewhere safe, and read the release notes for breaking changes. Then, for a stack you created in the web editor:
1. Open the stack, select the Editor tab, and select Update the stack without changing anything.
2. In the prompt, turn on Re-pull image and redeploy, then select Update. Portainer pulls the new image and recreates the container on it.

If you deployed the stack from a Git repository instead, select Pull and redeploy, turn on Re-pull image and redeploy, then select Update. Either way, it’s the same idea as updating Docker containers in Portainer for anything else you run.
If you’d rather update on your own schedule, replace stable with a version tag such as 2026.10.2 and change it when you’re ready.
After every update, check Home Assistant for any repair issues and look at the logs before you move on.
