How to Update Home Assistant in Docker Safely

Updating Home Assistant in Docker is different from updating a package inside a normal Linux system.

For a Docker-based install, you usually do not update Home Assistant from inside the Home Assistant UI. Instead, you replace the existing container with a new container created from a newer image, while keeping the same configuration directory or Docker volume.

This guide is for readers already running Home Assistant Core in a Docker container. It is not intended for Home Assistant OS or Supervised installations.

If you are setting up Home Assistant from scratch, or need to rebuild your container cleanly, start with Electromake’s guide: How to install Home Assistant in Docker.

Before You Update

A safe update starts before you pull a new image.

The goal is simple: know how the current container was created, preserve the configuration, and make the update repeatable.

1. Confirm whether you used Docker Compose or Docker CLI

Check the directory where you usually manage Home Assistant. Look for one of these files:

docker-compose.yml
compose.yaml
compose.yml

If you normally start Home Assistant with a long docker run command, or you do not have a Compose file, you may be using Docker CLI directly.

You can also list running containers:

docker ps

Look for your Home Assistant container name and image.

2. Check the current container details

Before replacing anything, record the current container settings.

docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Ports}}"

Then inspect the Home Assistant container:

docker inspect <container_name>

Pay attention to:

• container name
• image and tag
• bind mounts or named volumes
• port mappings
• network mode
• restart policy
• timezone setting
• any device passthrough options

The most important item is the configuration mount. If you recreate the container without the original configuration directory or named volume, Home Assistant may start as a fresh instance.

3. Back up the Home Assistant configuration

Back up the directory or named volume that contains your Home Assistant configuration.

For a bind mount, the path is usually visible in docker inspect. A simple directory backup may look like this:

sudo tar -czf home-assistant-config-backup.tar.gz /path/to/home-assistant/config

Replace /path/to/home-assistant/config with the actual path used by your container.

Why this matters: the container can be replaced, but your configuration, dashboards, automations, integrations, and local data live in the mounted configuration location. That is the part you must protect.

Review release notes before updating

4. Review release notes before updating

Before a major or monthly update, review the Home Assistant release notes.

This is especially important if your setup depends on:

• critical automations
• local discovery
• USB adapters
• Zigbee or Z-Wave devices
• custom integrations
• dashboards used by other people in the home

Do not rush an update if you cannot easily recover from downtime.

Method 1: Updating with Docker Compose

Docker Compose is the safer and more repeatable method for most Home Assistant Docker users because the container configuration is stored in a file.

With Compose, the update flow is:

1. go to the Compose directory
2. pull the newer image
3. recreate the container
4. check logs and verify Home Assistant

Step 1: Open the Compose directory

Go to the directory containing your Compose file:

cd /path/to/your/home-assistant-compose-directory

Check that the file is there: ls You should see something like: docker-compose.yml or compose.yaml

Step 2: Pull the updated image

For newer Docker Compose usage:

docker compose pull

Some older systems may still use the legacy syntax:

docker-compose pull

This downloads the image version referenced by your Compose file. If your Compose file uses a floating tag, the pulled image may change over time. If it uses a specific version tag, Docker will pull that specific version.

Step 3: Recreate the container

Run:

docker compose up -d

Legacy syntax:

docker-compose up -d

This recreates the Home Assistant container if the image changed, while keeping the configuration declared in the Compose file.

Step 4: Verify the Compose file still contains the right settings

Before or after the update, check that your Compose file still includes the expected settings:

cat docker-compose.yml

or

cat compose.yaml

Look for:

• the same configuration volume or bind mount
• the expected ports or network mode
• timezone environment variable, if used
• restart policy
• device passthrough entries, if your setup uses them

The exact file will vary between installations. The key point is that the updated container must be created with the same persistent configuration mount.

Step 5: Check logs after startup

docker compose logs -f

Or for a specific service name:

docker compose logs -f <service_name>

Legacy syntax:

docker-compose logs -f

Watch for startup errors, failed integrations, configuration problems, or repeated restarts.

Method 2: Updating with Docker CLI

Docker CLI updates require more care because the container configuration may exist only in your previous docker run command.

If you forget a volume, port, network mode, restart policy, timezone, or device option, the new container may behave differently from the old one.

Step 1: Inspect the existing container

List containers:

docker ps

Inspect the Home Assistant container:

docker inspect <container_name>

To extract some useful details:

docker inspect <container_name> --format '{{.Config.Image}}'
docker inspect <container_name> --format '{{json .Mounts}}'
docker inspect <container_name> --format '{{.HostConfig.NetworkMode}}'
docker inspect <container_name> --format '{{.HostConfig.RestartPolicy.Name}}'

Record the image, tag, mounts, ports, restart policy, network mode, environment variables, and any device mappings.

Step 2: Stop the old container

docker stop <container_name>

Stopping the container does not delete your mounted configuration directory by itself.

Step 3: Remove the old container

docker rm <container_name>

This removes the container object, not the bind-mounted configuration directory.

Be careful with commands that remove volumes. Do not delete the configuration directory or named volume unless you intentionally want to erase the installation data.

Step 4: Pull the updated image

Use the same image name and the tag you intend to run.

If your existing container used an image reference like <image>:<tag>, pull the desired replacement:

docker pull <image>:<tag>

If you want tighter version control, use a specific version tag. If you want the newest image referenced by a floating tag, use that tag intentionally and understand that it can change over time.

Step 5: Recreate the container with the same options

Recreate the container using the same configuration options you recorded earlier.

A simplified example looks like this:

docker run -d \
  --name <container_name> \
  --restart <restart_policy> \
  -v /path/to/home-assistant/config:/config \
  <image>:<tag>

If your original container used host networking, port mappings, timezone settings, USB devices, or other options, include them again.

For example, if your original setup used host networking, the recreated command must include that network setting too:

docker run -d \
  --name <container_name> \
  --restart <restart_policy> \
  --network host \
  -v /path/to/home-assistant/config:/config \
  <image>:<tag>

Do not copy these examples blindly. Match your existing installation.

Step 6: Verify the web UI

Check that the container is running:

docker ps

Then watch the logs:

docker logs -f <container_name>

Open the Home Assistant web UI and confirm that your configuration loaded correctly.

Docker Compose vs Docker CLI: Which Update Method Should You Use?

For most users, Docker Compose is the better update method.

Compose keeps the container definition in a file. That makes upgrades more repeatable because your volume mounts, network mode, restart policy, ports, and environment variables are written down.

Docker CLI can still work well for simple single-container setups, but it is easier to miss an option when recreating the container manually.

Method	Best for	Main advantage	Main risk
Docker Compose	Most Home Assistant Docker setups	Configuration is stored in a file	Compose file must be kept accurate
Docker CLI	Very simple manual setups	No Compose file required	Easy to forget flags during recreation

If you update Home Assistant more than once, Compose usually pays for itself quickly.

Verifying the Update

Do not stop after the container starts. A running container does not always mean Home Assistant is fully healthy.

Check the container state

docker ps

If the container is restarting repeatedly, inspect the logs:

docker logs --tail=200 <container_name>

For Compose:

docker compose logs --tail=200

Check the Home Assistant version in the UI

Open the Home Assistant web UI and confirm the displayed version after startup.

This verifies that the new container is actually running the expected image, not the old one.

Test the parts that matter

After the update, test your most important items first:

• critical automations
• dashboards
• integrations
• device control
• local discovery-dependent features
• USB-connected hardware, if used

Confirm restart behavior

If your setup depends on automatic startup after reboot, confirm the restart policy is still present.

docker inspect <container_name> --format '{{.HostConfig.RestartPolicy.Name}}'

A safe update should survive a host reboot without manual intervention.

Common Mistakes and Troubleshooting

Mistake: Updating from inside the Home Assistant UI

For a Docker-based Home Assistant setup, the update is performed by replacing the container with one created from a newer image.

The Home Assistant UI is useful for checking the version and reviewing the system after startup, but the Docker container itself is updated from Docker.

Mistake: Using the wrong image tag

Be intentional about tags.

A floating tag can make updates convenient, but it also means the image behind that tag can change. A specific version tag gives you tighter control and makes rollback planning easier.

Before updating, check what the current container is using:

docker inspect <container_name> --format '{{.Config.Image}}'

Mistake: Removing the configuration directory or volume

Removing the container is not the same as removing your configuration.

This is usually safe:

docker rm <container_name>

But commands that remove volumes or delete host directories can destroy your Home Assistant data if used carelessly.

Before removing anything, identify the mount:

docker inspect <container_name> --format '{{json .Mounts}}'

Compare it with your notes or backup.

Mistake: Forgetting host networking

Some setups use host networking. If the old container used host networking and the new one does not, behavior can change.

Check the old or current setting:

docker inspect <container_name> --format '{{.HostConfig.NetworkMode}}'

If your original setup used host networking, include it when recreating the container.

Problem: Permission issues after restoring files

If you restored or moved the configuration directory and Home Assistant cannot read or write files, inspect the directory permissions on the host.

Start with:

ls -la /path/to/home-assistant/config

The fix depends on how your container runs and how the files were restored. Avoid broad permission changes unless you understand their effect.

Problem: Container starts but the UI is unavailable

Check whether the container is running:

docker ps

Then check logs:

docker logs --tail=200 <container_name>

If you use Docker Compose:

docker compose logs --tail=200

Also verify that the expected ports or network mode were preserved.

Problem: Update completes but integrations or automations fail

Start by reading the logs and checking the Home Assistant UI for errors.

Then test the affected integration or automation directly. If the issue appeared immediately after an update, review the release notes and your configuration backup before making large changes.

Rollback Plan

Rollback is not just “run the old image again.”

A safe rollback needs two things:

1. the previous image version or tag
2. configuration data that is still compatible with that version

This is why a backup before updating matters. If the update changes configuration data or performs migrations, blindly downgrading the container may not be the safest recovery path.

A cautious rollback process is:

docker stop <container_name>
docker rm <container_name>

Then recreate the container using the previous image tag and the appropriate configuration data.

If you are unsure whether the configuration remains compatible, restoring from a known-good backup may be safer than downgrading against already-migrated files.

Maintenance Tips

Update regularly, but do not treat every update as urgent.

For a stable Home Assistant Docker setup:

• back up before updates
• review release notes before major or monthly changes
• keep your Compose file documented
• use explicit tags if you want tighter control
• periodically test that your backups can actually be restored

If you use Docker Compose, consider keeping the Compose file under version control. Even a small private repository can help you see what changed between updates.

For homelab and smart home setups running on a Raspberry Pi, mini PC, or similar Linux host, repeatability matters more than speed. A predictable update process is easier to debug when something breaks.

FAQ

Can Home Assistant in Docker be updated from the Home Assistant UI?

For this type of Docker setup, the update is done by replacing the container with one created from a newer image. Use Docker Compose or Docker CLI to update the container.

What should I back up before updating?

Back up the Home Assistant configuration directory or named Docker volume used by the container. This is the data you need to preserve when replacing the container.

How do I know whether I used Docker Compose or Docker CLI?

Look for a docker-compose.yml, compose.yaml, or compose.yml file. If you manage Home Assistant from that file, use Docker Compose. If you originally started it with a long docker run command and have no Compose file, you may be using Docker CLI directly.

What commands update Home Assistant with Docker Compose?

Use:

cd /path/to/compose-directory
docker compose pull
docker compose up -d
docker compose logs -f

On older systems, the command may be:

docker-compose pull
docker-compose up -d
docker-compose logs -f

What commands update Home Assistant with Docker CLI?

A typical flow is:

docker inspect <container_name>
docker stop <container_name>
docker rm <container_name>
docker pull <image>:<tag>
docker run -d --name <container_name> [same options as before] <image>:<tag>
docker logs -f <container_name>

The important part is recreating the container with the same configuration mount, network mode, ports, restart policy, and other required options.

How do I avoid deleting my Home Assistant configuration?

Identify the configuration mount before removing the container:

docker inspect <container_name> --format '{{json .Mounts}}'

Back up that directory or named volume. Do not delete the host directory or remove the named volume unless you intentionally want to erase the setup.

How do I check whether the updated container started correctly?

Use:

docker ps
docker logs --tail=200 <container_name>

Then open the Home Assistant web UI, check the version, and test important integrations and automations.

What should I do if Home Assistant does not start after the update?

Check the container logs first. Then verify that the recreated container has the original configuration mount, network mode, ports, restart policy, timezone setting, and any device passthrough options.

If needed, restore from your backup or roll back using the previous image version and compatible configuration data.

Should I use the latest tag or a specific version tag?

Use a specific version tag if you want tighter version control and easier rollback planning.

A floating tag can be convenient, but it may change over time, so use it intentionally.

How can I roll back if the update breaks my setup?

Stop and remove the updated container, then recreate it using the previous image tag and compatible configuration data.

If the update changed configuration data, restoring from a known-good backup may be safer than downgrading blindly.

Conclusion

The safest way to update Home Assistant in Docker is straightforward:

1. identify how the container was created
2. back up the configuration directory or volume
3. pull the desired image
4. recreate the container with the same settings
5. check logs
6. verify the UI, integrations, automations, and restart behavior

Docker Compose is the recommended approach for most users because it keeps the container configuration in a file and reduces the risk of missing a flag during updates.

If you are setting up Home Assistant from scratch or need to rebuild your container cleanly, refer to Electromake’s Home Assistant Docker installation guide before updating.