home-assistant.io/source/_includes/installation/container.md

Install Home Assistant Container

{% if page.installation_type != 'alternative' %} These below instructions are for an installation of Home Assistant Container running in your own container environment, which you manage yourself. Any OCI compatible runtime can be used, however this guide will focus on installing it with Docker.

Prerequisites

This guide assumes that you already have an operating system setup and a container runtime installed (like Docker).

If you are using Docker then you need to be on at least version 19.03.9, ideally an even higher version, and libseccomp 2.4.2 or newer.

Platform installation

Installation with Docker is straightforward. Adjust the following command so that:

• /PATH_TO_YOUR_CONFIG points at the folder where you want to store your configuration and run it. Make sure that you keep the :/config part.
• MY_TIME_ZONE is a tz database name, like TZ=America/Los_Angeles.
• D-Bus is optional but required if you plan to use the Bluetooth integration.

{% endif %}

{% if page.installation_type == 'alternative' %} {% include installation/container/alternative.md %} {% else %} {% include installation/container/cli.md %} {% endif %}

Once the Home Assistant Container is running Home Assistant should be accessible using http://<host>:8123 (replace with the hostname or IP of the system). You can continue with onboarding.

{% include getting-started/next_step.html step="Onboarding" link="/getting-started/onboarding/" %}

Restart Home Assistant

If you change the configuration, you have to restart the server. To do that you have 3 options.

1. In your Home Assistant UI, go to the Settings > System and click the Restart button.
2. You can go to the Developer Tools > Services, select the service homeassistant.restart and select Call Service.
3. Restart it from a terminal.

{% tabbed_block %}

• title: Docker CLI content: |

  docker restart homeassistant
  

• title: Docker Compose content: |

  docker compose restart
  

{% endtabbed_block %}

Docker compose

docker compose should already be installed on your system. If not, you can manually install it.

As the Docker command becomes more complex, switching to docker compose can be preferable and support automatically restarting on failure or system restart. Create a compose.yml file:

{% include installation/container/compose.md %}

Start it by running:

docker compose up -d

Once the Home Assistant Container is running, Home Assistant should be accessible using http://<host>:8123 (replace with the hostname or IP of the system). You can continue with onboarding.

{% include getting-started/next_step.html step="Onboarding" link="/getting-started/onboarding/" %}

Exposing devices

In order to use Zigbee or other integrations that require access to devices, you need to map the appropriate device into the container. Ensure the user that is running the container has the correct privileges to access the /dev/tty* file, then add the device mapping to your container instructions:

{% tabbed_block %}

• title: Docker CLI content: |

  docker run ... --device /dev/ttyUSB0:/dev/ttyUSB0 ...
  

• title: Docker Compose content: |

  version: '3'
  services:
    homeassistant:
      ...
      devices:
        - /dev/ttyUSB0:/dev/ttyUSB0
  

{% endtabbed_block %}

Optimizations

The Home Assistant Container is using an alternative memory allocation library jemalloc for better memory management and Python runtime speedup.

As jemalloc can cause issues on certain hardware, it can be disabled by passing the environment variable DISABLE_JEMALLOC with any value, for example:

{% tabbed_block %}

• title: Docker CLI content: |

  docker run ... -e "DISABLE_JEMALLOC=true" ...
  

• title: Docker Compose content: |

  version: '3'
  services:
    homeassistant:
    ...
      environment:
        DISABLE_JEMALLOC: true
  

{% endtabbed_block %}

The error message <jemalloc>: Unsupported system page size is one known indicator.