Note: this project is community-maintained and is not affiliated with Nabu Casa / official Home Assistant.
Warning: installing custom kernel modules on HAOS is unsupported and may lead to system instability or security issues. Use at your own risk.
Alert: the modules provided by this project are compiled with the same configuration as the official HAOS releases, but they are not signed with the HAOS private key. This means that they can be loaded on HAOS, but they will not be loaded automatically at boot and may require manual intervention to load.
Disclaimer: the modules provided by this project are intended for advanced users who understand the risks and implications of installing custom kernel modules on HAOS. The maintainers of this project are not responsible for any issues that may arise from using these modules.
Very Big Alert: the project is created and maintained with a heavy use of AI tools (GitHub Copilot, ChatGPT, etc.) to automate the generation of code and documentation. While this allows for rapid development and updates, it may also introduce errors or inconsistencies. Users are encouraged to review the code and documentation carefully before use.
Extra kernel modules for Home Assistant OS (HAOS) – automatically compiled for every new release.
Available modules:
The table below lists the top-level modules requested by this project. Each release also includes all runtime dependencies (other .ko files) that are discovered automatically and required by these modules but are not part of the standard HAOS kernel.
The table below is generated from config/modules.json and lists only the
top-level modules requested by this project. If one of these modules depends on
additional .ko files, the workflow discovers them with modinfo and ships
them automatically only when the full dependency chain is available.
| Module | Description | Notes |
|---|---|---|
xfs.ko |
XFS filesystem support | |
nfsd.ko |
NFS server daemon | |
nfs.ko |
NFS client support | |
quic.ko |
QUIC: A UDP-Based Multiplexed and Secure Transport (RFC 9000) – from lxin/quic | |
zfs.ko |
ZFS filesystem support – from openzfs/zfs | rpi3_64, rpi4_64, rpi5_64, yellow: ZFS (CDDL) is license-incompatible with GPL-only kernel symbols exposed by Raspberry Pi kernels (kernel_neon_begin/end, bpf_trace_run*, trace_event_*). |
Supported architectures: x86_64 and aarch64.
- hasos_more_modules
This project provides pre-compiled kernel modules for Home Assistant OS (HAOS) that are not included in the official HAOS releases. The modules are compiled for each HAOS release and made available as assets in the GitHub Releases of this repository.
For each top-level module requested, the build process also automatically discovers and includes all runtime dependencies (other .ko files) that are not part of the standard HAOS kernel. These dependencies are resolved via modinfo and packaged only when the complete dependency chain is available. This ensures that you download not just the requested module, but also all the kernel modules it depends on that aren't already in HAOS.
The primary use is by SambaNAS2 app (add-on) to provide support for the XFS filesystem and NFS server/client capabilities on HAOS. However, the modules can be used for any purpose that requires them.
Warning: installing custom kernel modules on HAOS is unsupported and may lead to system instability or security issues. Use at your own risk.
┌─────────────────────────────────────┐
│ GitHub Actions (main_build.yml) │
│ │
│ 1. check_releases.py │
│ └─ compares HAOS releases │
│ with already-built assets │
│ │
│ 2. patch_config.sh │
│ └─ modifies kernel.config │
│ to enable modules as =m │
│ │
│ 3. make linux-modules │
│ └─ compiles only .ko modules │
│ │
│ 4. modinfo dependency scan │
│ └─ discovers dependencies not │
│ included in HAOS release │
│ and packages them if all │
│ dependencies can be provided │
│ │
│ 5. GitHub Release │
│ └─ uploads .ko assets named │
│ {mod}_{ver}_{arch}.ko │
│ including all dependencies │
└─────────────────────────────────────┘
The workflow runs:
- Automatically every day at 06:00 UTC (cron).
- Manually from the Actions tab of the repository.
- Via API with a
repository_dispatchevent of typebuild-modules.
- SSH access enabled on HAOS (see Settings → System → SSH Access).
- HAOS version matching the module to install.
Download the .ko file matching your version and architecture from the
Releases page of this repository.
Example: xfs_13.2_x86_64.ko.
# Copy the file to the system (from an SSH terminal)
scp xfs_13.2_x86_64.ko root@homeassistant.local:/tmp/HAOS mounts the system partition (/) as read-only to ensure its
integrity. Before copying the module to its final location you need to
remount it as read-write:
# Remount / as read-write
mount -o remount,rw /
# Create the modules directory if it doesn't exist
mkdir -p /lib/modules/$(uname -r)/extra
# Copy the module
cp /tmp/xfs_13.2_x86_64.ko /lib/modules/$(uname -r)/extra/xfs.ko
# Update the module database
depmod -amodprobe xfs # load the module (and its dependencies)
# or
insmod /lib/modules/$(uname -r)/extra/xfs.koTo verify that the module was loaded correctly:
lsmod | grep xfs
dmesg | tail -20Warning: on the next update/reboot, HAOS remounts
/as read-only and files copied to/lib/modulesare removed. See the next section to make the module persistent.
The recommended method is to use the /mnt/data partition, which survives
HAOS updates.
/mnt/data/
└── modules/
└── <kernel-version>/
└── extra/
├── xfs.ko
└── nfsd.ko
Create the file /mnt/data/modules/load_modules.sh:
#!/bin/sh
# Load extra modules at HAOS boot.
KERNEL_VER=$(uname -r)
MODULE_DIR="/mnt/data/modules/${KERNEL_VER}/extra"
if [ ! -d "${MODULE_DIR}" ]; then
echo "[haos_more_modules] Module directory not found: ${MODULE_DIR}"
exit 0
fi
# Copy modules to the system location
mount -o remount,rw /
mkdir -p "/lib/modules/${KERNEL_VER}/extra"
cp "${MODULE_DIR}"/*.ko "/lib/modules/${KERNEL_VER}/extra/" 2>/dev/null || true
depmod -a
mount -o remount,ro /
# Load modules
for mod in xfs nfsd; do
modprobe "${mod}" 2>/dev/null && \
echo "[haos_more_modules] Module ${mod} loaded." || \
echo "[haos_more_modules] Module ${mod} not found or already built-in."
doneIf you use the Advanced SSH & Web Terminal add-on, you can add the command to
the ~/.profile file or to a custom s6-rc service.
For a permanent integration you can use the
AppDaemon add-on or create
an S6 script in /mnt/data/supervisor/addons/local/.
Linux kernel modules embed a string called "version magic" that must match exactly the string of the running kernel.
# Show the version magic of the running kernel
uname -r
# Show the version magic of the module
modinfo xfs.ko | grep vermagicIf the two strings do not match, loading the module will fail with:
ERROR: could not insert module xfs.ko: Invalid module format
Practical implications:
| Situation | Result |
|---|---|
| Module compiled for HAOS 13.2, running on HAOS 13.2 | ✅ Works |
| Module compiled for HAOS 13.2, running on HAOS 13.1 | ❌ Fails |
| Module compiled for HAOS 13.2, running after an upgrade to 13.3 | ❌ Fails |
Solution: always download the module that matches exactly the installed HAOS version. After every HAOS update you must replace the modules with the version compiled for the new kernel.
- Python ≥ 3.10
pip install -r requirements.txt
export GITHUB_TOKEN=ghp_... # optional, increases API rate-limit
python3 scripts/check_releases.py \
--haos-repo home-assistant/operating-system \
--this-repo dianlight/hasos_more_modulesTo add a new module to the workflow, edit the config/modules.json file and
add the top-level module name, description and the corresponding CONFIG_*
symbol to enable it in the kernel configuration.
Do not add dependency-only helper modules that require no config changes.
Those are resolved from the built .ko files with modinfo during the
packaging step and are included automatically only when the full dependency
closure is present.
# Copy a sample kernel.config
cp /boot/config-$(uname -r) /tmp/test.config
bash scripts/patch_config.sh /tmp/test.config x86_64
# Verify the patched values
grep -E "CONFIG_MODULES|CONFIG_LOCALVERSION|CONFIG_XFS|CONFIG_NFS|CONFIG_EXPORTFS" \
/tmp/test.configpython3 scripts/update_readme_modules.pyFor reproducible local simulation of one workflow variant (for example one
version + board matrix entry), see:
hasos_more_modules/
├── .github/
│ └── workflows/
│ └── main_build.yml # Main CI/CD workflow
├── config/
│ └── modules.json # Single source of truth for modules and CONFIG_* symbols
├── scripts/
│ ├── check_releases.py # HAOS missing-release detection
│ ├── modules_config.py # Reads config/modules.json for CI/docs
│ ├── collect_module_artifacts.py # Packages requested modules plus modinfo-resolved dependencies
│ ├── patch_config.sh # kernel.config patch (YAML-driven)
│ └── update_readme_modules.py # Regenerates README module table
├── .gitignore
├── LICENSE
├── README.md # This file
└── requirements.txt # Python dependencies
This project is distributed under the MIT license.
See the LICENSE file for full details.
