# openHABian: a self-configuring Debian setup for openHAB on a Raspberry Pi > openHABian packages the fiddly parts of running openHAB on a Raspberry Pi into a pre-built SD card image or a set of scripts, including a choice of openHAB major version and a config file you edit before first boot. The maintainers are blunt about the trade-off: dedicate the machine, because running extra software on it is how home automation setups become unreliable. **openhab/openhabian** — openHABian - empowering the smart home, for Raspberry Pi and Debian systems - Repository: https://github.com/openhab/openhabian - Website: https://community.openhab.org/t/13379 - Stars: 834 · Forks: 265 - Language: Shell - License: ISC - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/openhab-openhabian ## Two ways in: an SD card image or scripts on Debian openHABian provides a self-configuring Linux system setup for openHAB users, and it comes in two flavors. The first is an SD card image pre-configured with openHAB for all Raspberry Pi models, which is the path most people take. The second is a set of scripts that sets up openHAB and the surrounding tools on any Debian based system, which is what you want if your hardware is not a Raspberry Pi or if you already have a Debian box. The documentation makes a point that is worth repeating, because it explains the whole design: the image is really just Raspberry Pi OS lite under the hood, and openHABian is just some scripts that install a number of packages and configure the system in a specific way, optimized to run openHAB. That framing is honest and useful. It tells you that openHABian is not a magical appliance, and it also tells you that there is no technical barrier to putting other software on the same machine. The maintainers recommend against it anyway, and their reason is reliability rather than incompatibility. ## The version choice is made in a config file before first boot The one decision you have to make up front is which major version of openHAB to install, and it is made in openhabian.conf before the first boot rather than through a menu. openHABian installs openHAB 5 and Java 21 by default. To get openHAB 4 or openHAB 3 from the beginning you set clonebranch=openHAB4 or clonebranch=openHAB3 respectively, and clonebranch=legacy gives openHAB 2. Setting the key before first boot matters, because the installation is a one-shot process that fetches a specific branch, and changing it later is a different operation from choosing it upfront. The default being openHAB 5 with Java 21 has a knock-on requirement: openHAB 5 and Java 21 require a 64 bit image, and the recommended openHABian image is therefore the 64 bit version. The 64 bit switch has a cost, since it increases memory usage, so the guidance is a minimum of 2 GB of RAM on the Pi, with 4 GB on the safe side. You can check what you are running with the command getconf LONG_BIT. ## The hardware support list is narrow on purpose All Raspberry Pi models are supported as hardware as of openHABian version 1.6 and later, and openHABian can run on x86 based systems, but on those you have to install the OS yourself. Anything else ARM based, such as ODroids and OrangePis, may work or may not. NAS servers such as QNAP and Synology boxes will not work. The reason given for the narrowness is about testing rather than about the code. Supporting hardware means testing every patch and every release, and there are too many combinations of single board computers, peripherals and OS flavours for the maintainers to have available, or to have the time to test. The practical consequence for a user is that an unsupported configuration may work fine and you will get no help with it, because the forum support concentrates on the known set of issues. The documentation also points to fake hardware parameters for ARM hardware that is not supported, which simulate a Raspberry Pi and Raspberry Pi OS. The current hardware recommendation is a Pi model 4 or 5 with 2 or 4 GB of RAM, an Endurance SD card, and ideally the official 3A power supply. ## 32 bit Raspberry Pi users have a real upgrade path This is where the documentation is most opinionated, and the reasoning is sound. Many Raspberry Pi users are still on a 32 bit Linux, and openHAB 5 needs a 64 bit OS with Java 21. The 64 bit move has one major drawback, increased memory usage, which is not a good idea on heavily memory constrained platforms like older Raspberry Pi boards. The README therefore recommends not upgrading the distribution in place if you are still on an older release, but re-installing using the latest openHABian image and importing your configuration instead. That is a deliberate choice to make a clean start rather than mutate a running system, and it is the kind of advice that saves people from a half-upgraded box. There is also a Java version wrinkle in the same area. With openHAB 4 and Java 17, the buster and older distributions are no longer supported, and there will be issues when attempting to upgrade Java 11 to 17. The openHABian image sidesteps all of this because the image already contains a matching OS, Java and openHAB combination. ## Ubuntu is provided as-is, and some components break there Debian is the supported distribution, and the documentation is explicit about the status of everything else. As a manually installed set of scripts, openHABian supports x86 hardware on generic Debian. It provides code that is reported as-is to run on Ubuntu, but Ubuntu is not supported and the project asks that issues not be opened for it, while still welcoming pull requests. The reason is specific rather than general. Several optional components, such as WireGuard and Homegear, are known to expose problems on Ubuntu. That is a different posture from simply saying unsupported, because code is provided and contributors are invited to improve it, but the operating system contract is Debian. The consequences are practical. If your server runs Ubuntu, you are on your own with those optional components, and a forum thread about a WireGuard problem on Ubuntu will not get an answer. The repository structure reflects how the project is built, with functions/ and includes/ holding the shell logic, build-image/ and build.bash producing the SD card image, openhabian-setup.sh as the entry point, and a tests/ directory driven by BATS. ## SD mirroring is the answer to the SD card failure mode The single most common way a Raspberry Pi home automation setup dies is the SD card wearing out, and the documentation treats this as a first-class concern rather than an aside. It points to the SD mirroring feature and recommends getting a second SD card right away, the same model or at least the size of the internal one, plus a USB card reader. The mirroring setup means a failure of the primary card can be recovered from the mirror, which converts a hardware failure from an outage into a short interruption. The card choice matters too. Cards named Endurance can handle more write cycles and will be more enduring under openHAB's use conditions, and the same paragraph recommends the official 3A power supply, while noting that any old mobile charger will usually do. The wider recommendation is to dedicate the machine. Run the home automation on a system you dedicate to the task, prepared to run 24 hours a day, 7 days a week. The maintainers note that most people install a dedicated Raspberry Pi precisely because they do not install any other software there that might interfere with proper openHAB operation, and their judgement is that saving another 100 dollars is not worth putting the day-to-day reliability of your home at risk. ## ISC licensed, actively built, and versioned as openHABian The licence is ISC, which is the permissive licence the openHAB organisation uses across its tooling, and it comes with a LICENSE.md file in the repository root. The project is not archived and the last push was on 2026-09-24, with a build workflow, a ShellCheck workflow, a BATS workflow and a dedicated installation workflow, so the shell code is linted and the test suite runs on every change. The release history shows the project's own versioning scheme, which is separate from openHAB's: openHABian v1.12.0 on 2026-01-18, v1.12.0a on 2026-01-30 and v1.12.0b on 2026-02-01, with the letter suffixes marking pre-release builds. That pattern matters for upgrade planning, because the beta and alpha builds of a release are what the maintainers use to test the new version on real hardware before it settles. The repository also carries a NEWS.md, a CONTRIBUTING.md and a docs/ directory that includes the openhabian.md file referenced for the SD mirroring and fake hardware parameters, and the end-user installation instructions live in the official openHAB documentation at openhab.org rather than in this repository. ## Conclusion Adopt openHABian if you are setting up openHAB on a Raspberry Pi and want a known-good configuration instead of a weekend of package installs, and if you can dedicate that machine to the task. Do not adopt it on a NAS, on Ubuntu, or on a general-purpose server where you also want to run other software, since the project states those setups are unsupported and the maintenance guidance is to keep the system dedicated. Before you commit, edit openhabian.conf before first boot to set clonebranch, confirm your board has at least 2 GB of RAM if you go 64 bit, and buy a second SD card for the SD mirroring feature the documentation recommends. ## FAQ ### What is openHABian? It is a self-configuring Linux setup for openHAB, offered as an SD card image pre-configured with openHAB for all Raspberry Pi models, or as a set of scripts that set up openHAB and tools on any Debian based system. The project is licensed under ISC and the last push was on 2026-09-24. ### How do I choose which openHAB version openHABian installs? Edit openhabian.conf before the first boot. openHAB 5 with Java 21 is the default, clonebranch=openHAB4 or clonebranch=openHAB3 select the older majors, and clonebranch=legacy gives openHAB 2. ### Can I install other software on an openHABian system? Technically yes, since the image is Raspberry Pi OS lite with scripts that install packages, and the documentation says there is no genuine reason why it would not work. The recommendation is against it, because a dedicated system protects the reliability of your home automation, and the project also does not support Ubuntu or NAS servers such as QNAP and Synology boxes. ### Does openHABian work on a Raspberry Pi with 512 MB of RAM? The documentation says 512 MB can be sufficient for a smallish openHAB setup but not for a full system with many bindings and memory heavy features such as zram or InfluxDB. Since openHAB 5 and Java 21 require a 64 bit image, and 64 bit increases memory usage, the guidance is a minimum of 2 GB on the Pi with 4 GB on the safe side. ## Sources - [License: ISC](https://github.com/openhab/openhabian/blob/main/LICENSE) - [openhab/openhabian on GitHub](https://github.com/openhab/openhabian) - [Project website](https://community.openhab.org/t/13379) - [README](https://github.com/openhab/openhabian/blob/main/README.md) - [Releases](https://github.com/openhab/openhabian/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/openhab-openhabian