Open-source project
ptitSeb/box86 avatar
ptitSeb/box86

Box86's own documentation names two different paths for the same system config file

Box86 - Linux Userspace x86 Emulator with a twist, targeted at ARM Linux devices

3,822 stars252 forksCMIT

At a glance

What is it?
An MIT-licensed C emulator that runs 32-bit x86 Linux programs on 32-bit ARM Linux by translating calls to the host's own libraries, with an optional recompiler claimed to be five to ten times faster than the interpreter. Its newest release is from December 2024 while the branch was pushed in September 2026, a per-user config file outranks the command line, the debugger advice is to ignore segfaults, and the readme defers third-party code attribution to one source file.
Who is it for?
Box86 is worth knowing about if you want to run x86 Linux software or games on an ARM single-board computer and accept the setup cost, because the design choice that makes it usable is reusing the host's own C, math, audio and graphics libraries rather than emulating them, which is why it integrates with most applications at the cost of needing a 32-bit host. Three things to know before you try.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 26 days ago.
What is it written in?
Mainly C, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • ptitSeb/box863,822 ★ · +15
Star history
Repository2026-09-242026-11-15
ptitSeb/box863.8k3.8k

15 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The host must be 32-bit and the toolchain must be too

The readme states the requirement three times and in the strongest available words. You need a 32-bit subsystem to run and to build the emulator, the host must be 32-bit little-endian, and the project is described as useless on a 64-bit-only system. It goes further for builders: you need a 32-bit toolchain, a 64-bit-only toolchain will not compile it, and you will see an unrecognised architecture flag for 32-bit ARM, at which point you need a multiarch or chroot environment. The same trap is restated in the 64-bit notes, where the sibling project is introduced for running 64-bit binaries and then immediately caveated: to run 32-bit binaries you still need this emulator and a 32-bit chroot, which is also true on a real 64-bit x86 system. So the 64-bit sibling is an addition, not a substitute.

It borrows the host's libraries instead of emulating them

The mechanism is a sentence long and everything follows from it. The emulator uses the native versions of some system libraries, naming C, the math library, an audio library and OpenGL, and because of that it is easy to integrate with most applications and the readme says performance can be surprisingly high in many cases, linking a benchmark page it published in 2021. The same decision creates the graphics problem the readme spends a paragraph on: most x86 games need OpenGL, some ARM platforms only offer an ES subset or a poor implementation, so a translated OpenGL implementation may be necessary. And it is why the readme is a list of what works rather than a compatibility claim: several named titles, a family of game-engine titles, and an engine whose own OpenGL requirement may still be the thing that stops you.

The recompiler claims five to ten times, and links a post from 2021

There are two execution modes, an interpreter and a dynamic recompiler for the ARM platform, and the recompiler is credited with a speed boost between five and ten times over the interpreter alone. A blog post linked from the same paragraph explains the internals, and it is dated 2021, as is the performance page in the previous paragraph. Two things follow. The multiplier is the most quotable number in the readme and it is attached to nothing measurable: no hardware, no title, no figure, and a supporting page that has not been updated in four years. And both of the project's headline evidence links have aged at the same rate as the releases, which stopped in December 2024 while the branch kept taking commits.

A per-user config file outranks the command line

The configuration section is the part to read twice, because it inverts an expectation. Two files are loaded, one system-wide and one in the home directory, with the same syntax and an ini-like shape. The documented priority order is the per-user file first, then the system file, then the command line, and the readme spells out the consequence: your settings in the per-user file may override what you passed on the command line. So a flag you type can lose to a file you forgot about, silently. There is also a naming oddity in the same paragraph: the system-wide file is named for a different project than this one, and the readme then says the shipped default, which lives under the system directory in this repository, should be installed under the name matching this project. Two different filenames for what is conceptually one file.

The debugger advice is to stop stopping on segfaults

Because the recompiler uses memory protection and a segmentation fault handler to manage its generated code, a program that is running correctly will still raise faults that look exactly like crashes. The readme says this plainly and then gives the remedy for a developer: tell the debugger to ignore that signal, and place a breakpoint inside the emulator's own handler if you want to trap the faults you actually care about. It is honest, specific, and the kind of detail that only someone who has done this has written down. It is also a signal about how the recompiler works, since a design that turns expected control flow into a signal is trading predictability for the speed it claims. The graphics section has the same honesty: a named override variable for one board model and a driver debug variable for one driver, offered for the specific symptom of a game that starts and then quits before drawing anything.

Third-party code is acknowledged in one source file

A single sentence says that some internal opcodes use parts of another emulator's library, and points at one source file for the copyright details. That is a legitimate way to handle lifted code, and the file reference is specific enough to check, but it means the attribution for borrowed code lives in the code rather than in a notices file a reader would think to open. Two other third-party dependencies are named in the readme instead of hidden: a disassembler library you must install yourself to enable instruction tracing, and a compiler cache the readme tells developers to install before building. The readme also has the good habit of saying what this project is not, disambiguating it from a similarly named full-system emulator in a paragraph of its own.

Per-title bug reports go to a different repository

The compatibility list is not a file and not an issue tracker in this repository. It is the issues of a separate repository named for the compatibility list, so every title that does not work is reported somewhere else entirely. That is a defensible arrangement, because one tracker per title is easier to search than one enormous tracker, and it means this repository's own issues stay about the emulator. It also means a bug in the emulator found while chasing a title may be reported in the wrong place, and a reader who lands here first has to follow the link to find out where to write. The video section beside it is unusually thorough by comparison, with six named demonstrations across three hardware configurations and two of them credited to individual contributors.

Printers and syscall wrappers are generated, and the readme says so only in filenames

The repository root is where this project's scale shows. There is a CMake build with its own uninstall template, Debian and Arch packaging directories, a packaging script at the root with no file extension, a shell script for a specific third-party application, two Python scripts whose names say they rebuild things, a directory whose name says it helps build wrappers, a directory of prebuilt x86 libraries, and directories for tests, system files and documentation. Two of those names describe the most interesting mechanism in the codebase, that the printer and the syscall wrappers are generated rather than written, and the readme does not mention either of them. It does mention the two developer-facing dependencies that sit alongside that machinery: the compiler cache and the disassembler library.

Editorial conclusion

Box86 is worth knowing about if you want to run x86 Linux software or games on an ARM single-board computer and accept the setup cost, because the design choice that makes it usable is reusing the host's own C, math, audio and graphics libraries rather than emulating them, which is why it integrates with most applications at the cost of needing a 32-bit host. Three things to know before you try. It is useless on a 64-bit-only host, so you need a 32-bit subsystem and a 32-bit toolchain, and the sibling project that runs 64-bit binaries does not solve that. Its per-user config file takes priority over the command line, so a flag you pass can be silently overridden by a file in your home directory. And its recompiler installs a fault handler, which means a program under a debugger will look like it is crashing constantly unless you tell the debugger to ignore those faults.

Frequently asked questions

what is box 86

A userspace emulator that runs 32-bit x86 Linux programs on a 32-bit ARM Linux host, translating calls so that they use the host's own C, math, audio and graphics libraries. It has an interpreter mode and an optional dynamic recompiler for ARM, and it is described as useless on a 64-bit-only system.

How do I install Box86?

The readme links a separate compilation document rather than repeating the steps. What it does state is what you need first: a 32-bit host subsystem to run and build it, a 32-bit toolchain, and for builders a compiler cache. There is also a separate document for installing a Windows compatibility layer for it.

Does Box64 replace Box86 on a 64-bit ARM board?

No, it adds to it. The sibling project runs 64-bit binaries on 64-bit platforms, but the readme says you still need this emulator plus a 32-bit chroot for 32-bit binaries, and notes that the same is true on a real 64-bit x86 system.

Why does my Box86 flag get ignored?

Because the documented configuration priority puts the per-user file in the home directory above the system file and above the command line. The readme notes explicitly that settings in the per-user file may override what you pass on the command line.

Why does a Box86 program keep crashing under the debugger?

The dynamic recompiler manages its generated code with memory protection and a segmentation fault handler, so expected control flow shows up as faults. The readme suggests telling the debugger to ignore that signal and placing a breakpoint inside the emulator's own handler if you want to trap the real ones.

Official sources

  1. License: MIT
  2. Project website
  3. ptitSeb/box86 on GitHub
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/ptitseb-box86.svg)](https://hysenlabs.com/projects/ptitseb-box86)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/ptitseb-box86.svg)](https://hysenlabs.com/projects/ptitseb-box86)

Was this useful?