leanclr is a small C++ CLR for embedding C# in apps and games

The gap LeanCLR targets sits between CoreCLR and IL2CPP

The project states its own purpose in three terms: high ECMA-335 compatibility, low integration complexity and strong cross-platform capability, so that developers can really write C# and run anywhere. The problem it attacks is described by naming the two existing options and what each one costs. CoreCLR and Mono give full runtime capability, but their size, dependencies and host integration complexity are high, trimming and porting costs do not suit lightweight embedded publishing, and porting them to a new platform is hard and engineering heavy. IL2CPP is not open source, is tightly bound to the Unity ecosystem and toolchain, and supports only ahead of time publishing, with limited support for the ECMA-335 standard. LeanCLR is positioned to fill that gap: keep high ECMA-335 compatibility while offering an easy to integrate, trimmed and efficient cross platform implementation. The audience that follows from that positioning is specific. It is the team shipping a native application, a game, an embedded system or an in car platform that wants to run C# logic without taking a full runtime dependency, and that does not want to be bound to one engine's toolchain.

AOT plus interpreter, with no JIT in the pipeline

The execution model is the key architectural decision and it is stated plainly. LeanCLR uses an AOT plus interpreter hybrid execution architecture, does not support JIT, and is implemented in standard C++11 with no platform specific dependencies, which is what makes it runnable on any platform with a standard C++11 compiler without modification. That is a real constraint with real consequences. Without a JIT you cannot rely on runtime code generation, so hot paths are handled by translating IL to C++ ahead of time through the AOT compiler, whose status is listed as complete with support for IL to C++ translation. The LeanAOT component is described as the way to translate hot IL into C++ for good runtime performance, and the Core edition can either run purely interpreted or combine interpretation with LeanAOT for the hot functions. The interpreter is listed with hot function optimisation, so the design is not naive single pass interpretation. For the host, the practical benefit is the size. The Core single threaded version is stated to be under 600 KB on x64 and WebAssembly, and as low as 300 KB after trimming, which is the number that decides whether a runtime belongs in a game build or a device image at all.

The module checklist is where the compatibility claim lives

Rather than asking you to trust a compatibility percentage, the project publishes a per module status table, and reading it tells you exactly what is in place. Metadata parsing is complete, with full support for PE and COFF formats and the CLI metadata tables. The type system is complete, covering classes, interfaces, generics, arrays and value types. The IR interpreter is complete with hot function optimisation, and exception handling is complete with try, catch and finally plus nested exceptions. Reflection is complete with the core APIs such as Type, MethodInfo and FieldInfo. Delegates are complete with single cast, multicast and generic delegates. Internal calls are complete and currently based mainly on the Core version icalls, and P/Invoke is complete with manual registration as well as automatically generated P/Invoke wrapper functions through LeanAOT. Garbage collection is a precise mark and sweep full collection. What is not done is stated just as plainly. Multithreading, covering threads and synchronisation primitives, is listed as planned for the Standard version. That is the single most important line in the table for an adopter, and it is worth reading twice.

Standard and Core, with Core trimmed out of Standard

The project ships two editions, and the relationship between them is simple. Core is trimmed from Standard. Both have been implemented single threaded, and Standard's multithreading capability is still in the planning stage. The comparison table is explicit about what differs. On ECMA-335 both are standard implementations with high compatibility, and on the thread model both are single threaded, with multithreading planned for Standard. The cross platform row lists Windows, Linux, macOS, Android, iOS, HarmonyOS and WebAssembly for Standard, and all platforms in pure C++11 with no platform specific dependencies for Core. The garbage collection row is the same for both, a precise mark and sweep full collector. The Base Class Library row is where the split becomes a decision. Standard has mono, unity and coreclr branches, and implements more of the platform specific icalls, while Core carries a mono 4.5 Base Class Library with only some of its platform specific calls implemented. So Core is the smaller, more portable option for a pure scripting role, and Standard is the one to pick when you need a fuller Base Class Library and the platform specific calls that go with it.

The unity branch has the strongest measured evidence behind it

Compatibility claims are the part of a CLR project most likely to be aspirational, so it is worth looking at what is actually measured. The project reports three different levels for the three Standard branches. The unity branch is stated to be fully compatible with the Base Class Library of Unity 2019.4.x through 6000.3.x LTS IL2CPP, having passed all of the thousands of test cases. The mono branch is stated to be 99.95 percent compatible with the Mono 4.8 Base Class Library, with only one test case failing. The coreclr branch is in the middle of being brought up to the.NET 10 Base Class Library and is described as a work in progress that is being improved continuously. Read together, that is an honest spread rather than a marketing figure. The unity branch has the deepest evidence, since the leanclr-unity plugin is the shipped integration path for Unity. The mono branch is nearly there and the single failing case is a concrete thing to look up if you depend on it. The coreclr branch should be treated as experimental until the project says otherwise, and since the whole point of the project is a workable BCL, that distinction decides whether LeanCLR is a serious option for your stack today.

Engine integration is done for Unity and pending everywhere else

The ecosystem table is the honest measure of how far the reach extends. Unity and the Tuanjie engine on WebGL and mini game platforms is complete, through the leanclr-unity plugin, which replaces IL2CPP with LeanCLR when you publish a game, and the project describes that as substantially reducing package size and lowering memory use. Godot across all platforms is in development through the leanclr-godot plugin, and the .NET 10 CoreCLR Base Class Library work is in development on the Standard coreclr branch. Unreal Engine across all platforms is listed as planned with the release time undecided. The related repository list makes the same point from the other side: leanclr-unity is the shipping plugin, leanclr-unreal, leanclr-godot and leanclr-cocos are all in development, and HybridCLR is listed separately as a native C# hot update scheme for Unity across platforms. There are also third party efforts in the same space, including a Godot plugin and UnrealCSharp, a C# plugin for Unreal built on .NET 10. Two demos exist for a quick look. leanclr-demo has a win64 example that runs with run.bat and an h5 WebAssembly browser example served over HTTP from index.html, and leanclr-unity-demo shows how the plugin replaces IL2CPP with the LeanCLR runtime when publishing WebGL, mini game or Win64 targets.

Where the small footprint stops being the deciding factor

There are cases where LeanCLR is the wrong tool, and they are worth naming before you start. If you need real multithreading in managed code, this is not there yet, and the project says so. If your application depends on a Base Class Library area that only the coreclr branch is beginning to cover, you are depending on work in progress. If your team already standardises on CoreCLR or Mono and the deployment target can absorb the size, the integration simplicity argument largely disappears, since a full runtime gives you the complete BCL and a mature ecosystem instead. There is also a strategic dimension that the project itself is clear about: the alternative it is displacing, IL2CPP, is closed source and Unity bound, and LeanCLR is not, so choosing it is partly a bet that an open, portable runtime serves your needs better than the convenience of a vendor toolchain. The upside of that bet is stated in the project documentation, in its full documentation site at doc.leanclr.com with sections for getting started, building and integration, AOT, interoperability, testing and contributing, and the plugin route means the practical path for a Unity team is to swap the runtime behind their existing project rather than rewrite it.

Editorial conclusion

Adopt LeanCLR when you are embedding C# logic in a host, a game or an embedded device where a full CoreCLR or Mono runtime is too heavy and IL2CPP is not an option because it is closed source or does not accept your assembly. Do not adopt it if you need multithreading today, since both editions are single threaded and threading is still listed as planned, and do not adopt it if you need a specific Base Class Library you have not checked. Before you start, confirm which Standard branch matches your Base Class Library, the unity branch for Unity hosts, mono for a Mono 4.8 target, or coreclr for .NET 10, and read the getting started and integration pages on the documentation site before committing to the runtime.

Frequently asked questions

Official sources

1. focus-creative-games/leanclr on GitHub
2. Issues
3. License: MIT
4. README