libhybris: running Android hardware drivers inside a glibc process

The unit of reuse is a driver, not an application

The README states the purpose in two sentences. libhybris is a way to load drivers compiled for Android from regular Linux processes, which means it allows you to load drivers that link against the bionic C library inside processes whose native C library is glibc, musl or something else.

That distinction matters, because it is narrower and more useful than it first sounds. This is not an Android emulator, not an app runtime, and not a compatibility layer for Android applications. It is a bridge that lets one process hold two C library worlds at once: the bionic world the driver was compiled for, and the glibc or musl world the host process runs in.

The payoff is that a distribution can inherit hardware support it could not otherwise afford to write. Graphics drivers, and any other driver sitting inside an Android so file, become usable in a non-Android Linux distribution.

The audience is therefore specific. Distribution maintainers building a Linux system for Android derived hardware, and device vendors porting an existing Android hardware adaptation layer to a different base, are the people who benefit. A developer who wants to run Android apps on a laptop is in the wrong place entirely.

A stripped Android system runs as a systemd service or a container

The interesting part of the design is what surrounds libhybris. The README explains that Android is patched to remove TLS accesses in bionic, which usually cause problems with glibc TLS slots. Android is also patched to remove zygote, surfaceflinger, bootanim and other processes that are not needed when running a regular Linux distribution, or would cause problems.

The result is a stripped down Android system, and that is launched as a systemd service or as a container by the Linux distribution's init. Its purpose is to provide the hardware adaptation services that are mandatory to be able to use Android drivers.

So the architecture is two layered. The stripped Android userspace supplies the services the driver expects to find, and libhybris is what lets the host process call into that driver's bionic-linked code.

The TLS patch deserves attention because it explains why this cannot be a naive shared object load. The two C libraries have incompatible thread local storage models, and the pieces that would collide were removed from Android rather than worked around. That is the kind of detail you only learn from a project that has actually been ported to several distributions.

Building means compiling against headers for your target Android version

There is no install command in the README and no package feed is named, so the honest description is that you build it from source, and the build has one hard external requirement: you need android-headers to compile against the Android version you are targeting.

That requirement is not a formality. The headers define the ABI and the platform APIs that the driver side of the bridge expects, and the version has to match the Android system you are going to run alongside it. The README links two helper scripts that extract headers, one in the libhybris repository itself and one in the mer-hybris droid-hal-device repository.

utils/extract-headers.sh

That script path is the practical starting point for a porter, because it produces the header tree the build needs.

The repository layout reflects the three parts of the system. The hybris directory holds the compatibility layer itself, compat holds the compatibility glue for the C library interfaces, and utils holds the helper scripts. The build uses git submodules, given the .gitmodules file at the root, so a shallow clone without submodules will not produce a working build.

The README also names two projects that document this process rather than leaving you to reconstruct it: the SailfishOS Hardware Adaptation Development Kit, which documents how to port SailfishOS on top of Android, and Halium, which provides a standardized and containerized abstraction between the Android system and the Linux distribution.

Graphics need a compositor plugin, audio needs a wrapper

Loading a driver is only half the job, and the README is candid about the rest of the work.

For graphics the problem is that Android uses hardware composer, and that has to be accounted for by using, for example, a plugin to the Qt compositor if Qt is being used. The mer-hybris qt5-qpa-hwcomposer-plugin is the reference implementation named in the README. In other words, if your desktop is Qt based, the driver does not simply light up the panel; a platform plugin has to translate between the compositor and the Android graphics stack.

Audio follows the same shape. Wrappers need to be developed that bridge the Android functionality into the corresponding Linux distribution, and the example given is the mer-hybris pulseaudio-modules-droid, which provides PulseAudio modules for the Android audio path.

This is the pattern to internalise. libhybris gives you the ability to load the driver; it does not give you a Linux desktop that uses it. Each subsystem needs its own bridge, and those bridges live in separate projects that you adopt and maintain. Anyone budgeting a port should budget for the wrappers, not just for the library.

Since Android 8 many drivers moved to binder-IPC instead

The additional notes section contains the most important piece of guidance for anyone starting today. Since Android 8, many of the drivers, except those which require the highest possible performance like graphics drivers, have been implemented via binder-IPC.

The distinction drawn is between two classes of driver. Performance critical drivers such as graphics drivers are still implemented in the classic way, and libhybris is the tool for those. Everything else has largely moved to binder-IPC, where the driver talks to a remote service rather than exposing an in-process interface.

For those binder based drivers, the README says it is sometimes easier to use binder-IPC directly from a native context, and points to the glib based binder implementation in mer-hybris libgbinder, with an example of usage in the mer-hybris bluebinder project.

So the honest guidance is that libhybris is the right tool for the older, in-process style of driver, and libgbinder is the right tool for the modern style. Reaching for libhybris first on a recent Android device may mean you picked the harder path, and the two live in different organisations with different release cycles.

The performance caveat in the README also tells you where the two approaches divide. If your driver needs every cycle, in-process and hybrid wins. If it needs to survive a process boundary, binder is the native Android answer and pretending otherwise costs you.

Seven licence files and a licence GitHub cannot classify

The licence story for libhybris is unusual enough that anyone planning to ship it in a product needs to look at it directly. The repository root carries LICENSE.Apache2, LICENSE.BSD-2, LICENSE.BSD-3, LICENSE.BSD-4, LICENSE.GPL3, LICENSE.ISC, LICENSE.LGPLv21 and LICENSE.MIT files.

That set of files covers the code inherited from many sources, where each third party component keeps its own terms. It is a common pattern for compatibility layers, because they incorporate code from many origins.

The consequence for you is that the single top level LICENSE file is not the whole answer, and the repository is recorded as having a custom licence that GitHub cannot classify, which is why the licence field reads Other. Any legal review of your use has to go through the individual files and the per file headers rather than assuming one Apache or one MIT grant applies to everything.

This is not legal advice, and the point is not that the licences are hostile. It is that a permissive-looking quick read of the repository metadata will be wrong, and the classification exists precisely because there is no single blanket grant.

No releases, and the surrounding projects carry the porting work

The repository has no GitHub releases at all, and the last push was on 2026-06-24. For a project of this kind that is not by itself a warning sign, since libhybris is consumed as source by distribution packaging rather than as a downloaded binary, and its behaviour is tied to the Android version and the driver set you are targeting.

What matters more is where the work actually lives. The README points at two ecosystems for the heavy lifting. Halium provides a standardized and containerized abstraction between the Android system and the Linux distribution, and it is used by Droidian, FuriPhone, Ubuntu Touch and others. SailfishOS publishes the Hardware Adaptation Development Kit, which documents how to port SailfishOS on top of Android.

That is the real difference in approach between the options. Using libhybris directly means you take on the header extraction, the patched Android system, the compositor plugin and the audio wrappers yourself. Adopting Halium or the SailfishOS HADK means you inherit a documented path and an existing set of bridges, and you accept their constraints instead of designing your own.

The repository also carries a .travis.yml, which dates the continuous integration setup to an earlier era of tooling, and the absence of any tagged release in that context means you should track the branch rather than a version number.

Editorial conclusion

libhybris suits a distribution team or a device vendor that already ships an Android derived hardware stack and wants its drivers reused by a glibc based system, and the pattern of running a stripped Android system as a systemd service or container is the only way the README describes for getting those drivers to work. It does not suit a project that just wants to run an Android application on Linux, since the unit of reuse here is a driver, not an app, and it does not suit a distribution whose graphics stack is already native, because the extra Android userspace layer would be pure overhead. Before you commit, check that you can obtain android-headers for the exact Android version you are targeting, because the build compiles against them, and confirm that the driver you need is one that can be adapted, since Android 8 many drivers have moved to binder-IPC and want libgbinder rather than libhybris.

Frequently asked questions

Official sources

1. Issues
2. libhybris/libhybris on GitHub
3. README