box64/README.md

Box64: Linux Userspace x86-64 Emulator with a Twist

Changelog | 中文 | Українська | Report an Error

---

Box64 enables running x86_64 Linux programs, including games, on non-x86_64 Linux systems such as Arm (64-bit little-endian host system required).

Check out Box64 in action on YouTube:

• MicroLinux
• Pi Labs
• The Byteman

Box64 leverages native system libraries (libc, libm, SDL, OpenGL), offering ease of integration and surprising performance in many applications. For performance benchmarks, check this analysis.

With DynaRec for ARM64, RV64 and LA64 platforms, Box64 achieves a speed boost 5-10x faster than the interpreter alone. For a deeper look at DynaRec, see Inner workings.

Logo and icon by @grayduck - Thank you!

---

📖 Usage

Box64 offers environment variables to control its behavior. For details, see Usage Documentation.

---

🚀 Compiling and Installation

• Compilation Instructions
• Wine Installation for Box64

---

🔄 Version History

See the Changelog for version updates.

---

🖥️ Platform Compatibility Notes

Box64 requires 64-bit libraries on the host system, as it directly translates x86_64 function calls. For 32-bit binaries, use Box86.

Notes

1. Box32 mode is in the making, which aims to support 32-bit binaries on Box64, stay tuned!
2. Some installers may default to x86 on 64-bit host OSes, causing compatibility issues. Workaround: Use a fake uname that returns "x86_64" for -m.

---

⚙️ Configuration

Box64 has configuration files located in /etc/box64.box64rc and ~/.box64rc, both formatted as .ini files. If you don’t want to use the default /etc/box64.box64rc file, copy it to ~/.box64rc to ensure compatibility.

Settings priority: ~/.box64rc > /etc/box64.box64rc > Command line.

---

📄 Additional Platform-Specific Notes

Unity Game Emulation

• Many Unity games require OpenGL 3+, which may be challenging on ARM/RISC-V SBCs.
• Tip for Pi4 and Pi5 Users: Set MESA_GL_VERSION_OVERRIDE=3.2 with BOX64_DYNAREC_STRONGMEM=1 to prevent freezes and enable strong memory mode.
• Using Panfrost: For better compatibility on ARM, enable PAN_MESA_DEBUG=gl3 to force higher OpenGL profiles. This can help if a game starts but quits unexpectedly before showing any content.

GTK Programs

Box64 wraps GTK libraries, supporting both gtk2 and gtk3.

Steam

Steam requires Box86 due to its 32-bit client app, but uses 64-bit local server binaries. Systems with less than 6GB RAM may need a swap file for optimal performance.

Wine

Box64 supports Wine64 and Proton. For 32-bit components, Box86 is required. Systems with both Box64 and Box86 can run 32- and 64-bit Windows programs.

Note: You can use Wine WOW64 build to run x86 Windows programs in Box64-only environments, this is still experimental, but it works in most cases.

Vulkan

Box64 wraps Vulkan libraries.

---

Final word

I want to thank everyone who has contributed to box64 development. There are many ways to contribute: code contribution, financial, hardware and advertisement! So, in no particular order, I want to thank:

• For their major code contribution: rajdakin, mogery, ksco, xctan
• For their major financial contribution: Playtron, tohodakilla, FlyingFathead, stormchaser3000, dennis1248, sll00, libre-computer-project, CubeCoders Limited
• For hardware contribution and LoongArch migration: xiaoji, Deepin Beijing Develop Team
• For their hardware contribution: ADLINK with Ampere, SOPHGO, Radxa, StarFive, Pine64, AYN, AYANEO, jiangcuo
• For their continuous advertisements for the box64 project: salva (microLinux), PILab/TwisterOS team, The Byteman, NicoD, ekianjo (Boilingsteam)

And I also thank the many other people who participated even once in this project.

(If you use Box64 in your project, please don't forget to mention it!)