Box86: running 32-bit x86 Linux programs on 32-bit ARM

The problem Box86 solves: x86 binaries on ARM without emulating the system libraries

Most emulators translate an entire machine, including the operating system calls the guest makes. Box86 takes a narrower route. It lets you run x86 Linux programs, such as games, on non-x86 Linux systems like ARM, where the host system needs to be 32-bit little-endian. The twist is that Box86 uses the native versions of some system libraries, including libc, libm, SDL and OpenGL, so the emulated program calls into the host's own libraries rather than into emulated copies. The README argues this makes integration with most applications easy and can give surprisingly high performance in many cases, and it points to a benchmark analysis on box86.org as an example.

That design also produces the project's central constraint. Because calls go straight from x86 to the host, the host must already have 32-bit libraries. Box86 contains no 32-bit to 64-bit translation layer. On an ARM64 platform, the documentation says you build Box86 for ARM 32-bit and keep a chroot with 32-bit libraries. The audience is therefore narrow and specific: people with a 32-bit ARM userspace, often an armhf environment on top of an aarch64 OS, who want to run x86 software without a full system emulator.

How the translation works, and what the DynaRec changes

Box86 translates function calls from x86 to the host system directly. That is the sentence the README uses to explain both the performance story and the 32-bit requirement: the host needs 32-bit libraries because the translation does not cross a pointer-size boundary.

The project also integrates a DynaRec, a dynamic recompiler for the ARM platform. The README states it provides a speed boost between 5 to 10 times faster than using only the interpreter, and links to a high-level explanation of the Dynarec on box86.org. That number is the project's own claim, not an independent measurement, and it applies to the DynaRec path rather than to every program.

The DynaRec has a debugging side effect worth knowing before you attach a debugger. It uses memory protection and a segfault signal handler to manage JIT code. In practice, if you debug a program that uses JIT'd code, such as mono or Unity3D, you will see many normal segfaults firing. The README suggests `handle SIGSEGV nostop` in GDB so the debugger does not stop at each one, and mentions placing a breakpoint inside `my_box86signalhandler` in `signals.c` if you want to catch real segfaults. That is an honest description of a trade-off the JIT design imposes on tooling.

Installing Box86 and running a first x86 program

The README does not put build steps inline. It points to two documents: compilation instructions in docs/COMPILE.md, and instructions for installing Wine for Box86 in docs/X86WINE.md. A debian/ directory and pkgbuilds/ directory exist at the top level, and the repository ships an install_steam.sh script, but the README itself does not document package installation or a rollback path. Treat the two docs as the source of truth.

Before any of that, confirm you have the prerequisites the README insists on. You need a 32-bit subsystem to run and build Box86, and a 32-bit toolchain to compile it. A toolchain that only supports 64-bit will not compile the project; on aarch64 the README says you typically get `-marm` not recognized, and you will need a multiarch or chroot environment.

If you are building from source, the README says you should install ccache and build Box86 with it, using ccmake for example. The project is configured with CMake, as the top-level CMakeLists.txt indicates. The README does not give a configure command line, so check docs/COMPILE.md for the exact CMake invocation and any install target before running one; the presence of cmake_uninstall.cmake.in suggests an install rule exists in the CMake files.

To enable TRACE, which dumps every x86 instruction executed to stdout along with a register dump, you also need the Zydis library available on your system. That is a build-time dependency for a debugging feature, not something every user needs.

Box86 also reads two configuration files, `/etc/box4.box86rc` and `~/.box86rc`. Both use the same syntax and are basically ini files: a section in square brackets defines the process name, and the rest of the file sets environment variables. The README points to USAGE.md for the full list of parameters, and says Box86 comes with a default file, though the README text available here is truncated at that point.

If you need Wine, follow docs/X86WINE.md. The README does not document a canonical command line for launching a program, so read USAGE.md and COMPILE.md rather than inventing flags.

Where Box86 fails: 64-bit hosts, OpenGL, and the chroot tax

The clearest failure mode is stated in capital letters in the README: you need a 32-bit subsystem to run and build Box86, and Box86 is useless on 64-bit only systems. If your ARM board runs a pure aarch64 userland with no armhf libraries, Box86 is not a partial solution, it is no solution. The README's note on 64-bit platforms repeats this: to run Box86 on ARM64 you build for ARM 32-bit and keep a chroot with 32-bit libraries. That chroot is real operational cost, not a footnote.

OpenGL is the second practical wall. Most x86 games need OpenGL, and on ARM platforms a solution like gl4es might be necessary. Some ARM platforms only support OpenGL ES, or their OpenGL implementation is described in the README as dodgy, with a pointer to notes about OpenGL on Android. Unity3D games are cited as working fine, but the same OpenGL requirement can block them on some ARM platforms. So compatibility is not only about the CPU emulation path; the graphics stack can decide whether a title runs at all.

A third limitation is documentation scope. The README says many games just work without much tweaking and names WorldOfGoo, Airline Tycoon Deluxe and FTL, plus GameMaker Linux titles such as UNDERTALE, A Risk of Rain and Cook Serve Delicious. That is a list of examples, not a guarantee. The project maintains a separate compatibility list at github.com/ptitSeb/box86-compatibility-list/issues, which is where you check a specific title before assuming it works.

Box86 versus Box64, QEMU and FEX

Box64 is the sibling project, and the distinction is about binary width, not about quality. Box86 runs x86 binaries; Box64 runs x86_64 binaries on 64-bit platforms. The README is explicit that you still need Box86 and a 32-bit chroot to run x86 binaries, in the same way an actual x86_64 Linux needs x86 libraries and binaries in multiarch to run 32-bit software. If your goal is a 64-bit x86 program on ARM64, Box86 is the wrong project and Box64 is the right one.

QEMU takes a different approach: it is a general system and user-mode emulator that emulates the guest environment more completely, which is why it can run software Box86 cannot. The cost is that Box86's native-library design is what lets it skip emulating libc, libm, SDL and OpenGL. That is the actual trade: Box86 gains integration and speed by giving up the ability to run without a matching 32-bit host userspace.

FEX is another x86-on-ARM approach that appears in the search data alongside Box86. The README does not describe FEX's internals, so the honest comparison is limited to the architectural point already made: Box86's defining choice is direct translation of calls into native 32-bit libraries, and any alternative that emulates more of the environment will differ on exactly that axis.

One naming trap the README calls out: do not confuse this project with 86box, a full-system emulator specialized in early to fairly recent PC hardware. They share a similar name and nothing else.

Maintenance, releases and the MIT licence

The repository is not archived, and the last push was on 2026-09-11, which is recent enough that the codebase is being touched. Recent tagged releases, however, are spaced out: v0.3.8 on 2024-12-06, v0.3.6 on 2024-05-21, and v0.3.4 on 2023-12-15. If you depend on tagged versions rather than on master, plan around a release cadence measured in months, not weeks. The README links to docs/CHANGELOG.md for the version history.

Upgrade cost is dominated by the build environment rather than by the source. Because Box86 needs a 32-bit toolchain and, on 64-bit hosts, a 32-bit chroot, every rebuild inherits that setup. The README recommends ccache, which is itself a signal that rebuilds are expected to be frequent for developers. The project ships a rebuild_printer.py and rebuild_wrappers.py at the top level, and a wrapperhelper/ directory, which suggests parts of the wrapper layer are generated rather than hand-written. That matters if you plan to patch wrappers: check whether your change survives regeneration.

Box86 is MIT licensed. That is a permissive licence, and the practical implication is that redistribution and modification are allowed under its terms. This is not legal advice; read the LICENSE file in the repository for the actual text. One detail worth noting for anyone vendoring code: the README states that some x86 internal opcodes use parts of the Realmode X86 Emulator Library, and points to src/emu/x86primop.c for the copyright details. If you are auditing licence obligations, that file is where the non-Box86 notices live.

Editorial conclusion

Box86 is for people running 32-bit x86 Linux games or applications on a 32-bit little-endian ARM system, especially when a 32-bit userspace with libc, libm, SDL and OpenGL is already present. It is the wrong tool on a 64-bit only system: the README states Box86 is useless there, and x86_64 binaries belong to Box64. Before adopting it, verify three things: that your host is 32-bit little-endian, that a 32-bit toolchain can build the project, and whether your target needs OpenGL, in which case check the gl4es option. The build instructions live in docs/COMPILE.md and the Wine setup in docs/X86WINE.md, so start there rather than guessing at flags.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. ptitSeb/box86 on GitHub
4. README
5. Releases