The goal of this Article is to teach you how to find out what takes how much space on your HAOS system.
At the end of this article you should have an interactive way to explore your storage similar to this.
First some background to understand how HAOS and its storage works.
Almost everything is run in docker containers. Every addon, even HA itself or the supervisor are docker containers.
Some paths on the OS are bind mounted into those containers so multiple addons can have access to the same files and to persist data. Containers are considered ephemeral/replaceable. Here's some examples of paths that might be shared and where they originate
| Path on OS | Path in container/addon |
|---|---|
/mnt/data/supervisor/share/ |
/share |
/mnt/data/supervisor/homeassistant |
/config or /homeassistant |
/mnt/data/supervisor/backup |
/backup |
What this means is that addons don't have access to everything on the OS side so if you want to check what takes space on there you have to use some tricks.
HAOS architecture diagram. Source for picture.
As explained above, addons can only see certain things but this might be all you need.
Run this to install and start gdu.
apk add gdu
# Use this if you want to ignore shares/mounts
gdu --ignore-dirs /share /
# Otherwise use this
gdu /Then press m (file modification dates) and c (file counts) and i (item info) and look around with the arrow keys.
Press ? for shortcuts, q to close modals. Ask before deleting anything if you're unsure 😉
gdu is currently in alpine's (Alpine is the base OS most addons use) 3.20 branch: https://pkgs.alpinelinux.org/packages?name=gdu&&arch=x86_64
The advanced SSH addon uses this already at the time of writing but the core SSH addon still uses 3.19.
As such I recommend the former. We'll use ncdu for the Core Addon which is similar but slower with fewer options.
Run this to install and start ncdu
apk add ncdu
# Use this if you want to ignore shares/mounts
ncdu -e --exclude /share /
# Otherwise use this
ncdu -e /Then press m (file modification dates) and c (file counts) and i (item info) and look around with the arrow keys.
Press ? for shortcuts, q to close modals. Ask before deleting anything if you're unsure 😉
As explained in the introduction this requires OS level access. To achieve this we bind mount the root / path of the OS into the /mnt path of a temporary docker container.
This is made possible by using the Advanced SSH addon with disabled protection mode.
To make it harder to accidentely delete anything the commands use :ro to mount the path read only.
You need the Advanced SSH addon with disabled protection mode (restart it after disabling it) to get access to the docker command.
You can then run one of these docker commands
# We ignore /var/lib/docker because it's the same as /mnt/data/docker (bind mount) and would be counted twice otherwise
# Use this if you want to ignore shares/mounts
docker run --rm -ti -v /:/mnt:ro alpine sh -c "apk add gdu; gdu --ignore-dirs /mnt/var/lib/docker --ignore-dirs /mnt/mnt/data/supervisor/share --ignore-dirs /mnt/mnt/data/supervisor/mounts /mnt"
# Otherwise use this
docker run --rm -ti -v /:/mnt:ro alpine sh -c "apk add gdu; gdu --ignore-dirs /mnt/var/lib/docker /mnt"This is a very simple and universal way using standard linux tools that works for addons and OS alike. I only recommend this if you are unable to use the other ways. For example due to too little space or lack of network connectivity.
It's a more rudimentary non-interactive option which you likely don't want to use any more once you've used the other ways above.
The paths are different (see introduction for why) depending on if you use an addon or not. Don't panic, this can take a few seconds to return anything depending on how fast your system/storage is.
du -shc /* | sort -h
du -shc /bigdirectory/* | sort -h
# du -shc /bigdirectory/.../* | sort -h and so on...