Cpp2IL: reversing Unity's IL2CPP builds back to managed DLLs

What Cpp2IL is for, and who actually needs it

Unity can compile a game's C# code ahead of time through IL2CPP, which turns managed assemblies into native code plus a metadata file. The original DLLs are gone from the shipped build. Cpp2IL exists to walk that process backwards: it reads the IL2CPP metadata and binary, reconstructs an intermediate representation, and emits managed DLLs again. The README describes it plainly as a "WIP Tool to reverse Unity's IL2CPP build process back to the original managed DLLs."

The audience is narrow and technical. Modders who need to read a game's method bodies, security researchers looking at how a Unity title handles input or network data, and tooling authors who want the parsed metadata rather than a finished DLL. It is not a general .NET decompiler and it is not aimed at people who just want to poke around an app. If the target is a Mono build, Cpp2IL has nothing to offer; the metadata layout it parses only exists because of IL2CPP.

LibCpp2IL, ISIL and the analysis pipeline

The repository is split so that parsing and reconstruction are separable. LibCpp2IL handles the initial parsing and loading of metadata structures, and the README notes it can be taken from the build artifacts by anyone who wants to work with IL2CPP metadata directly. It is MIT licensed, same as the main project.

The CLI is a wrapper around Cpp2IL.Core. The README points to Cpp2IL.Core/README_CORE.md for using that module in your own projects, which is the path to take if you want the library rather than the executable. Inside the core, decompilation starts at MethodAnalysisContext.Analyze(). That translates platform-specific assembly into ISIL, an instruction-set-independent intermediate representation, using Cpp2IlInstructionSet. From there it builds a control flow graph and dominator information, then runs a sequence of IAction classes held in MethodAnalysisContext.analysisActions: stack analysis, simplification, applying metadata, and so on. Ilgenerator.GenerateIl() finally turns ISIL into CIL, which is written into managed DLLs.

The rewrite dropped Mono.Cecil in favour of AsmResolver.DotNet. The README is candid about why: the project had become dependent on Mono.Cecil and hit its limitations, and untangling that dependency was part of the motivation for the rewrite. The application is now written around LibCpp2IL types and the analysis context objects. A plugin system is also in progress, intended to let third parties add custom instruction sets, binary formats, and eventually support for obfuscated or encrypted metadata and binaries. The repository already carries plugin projects such as Cpp2IL.Plugin.Mfuscator, Cpp2IL.Plugin.Pdb and Cpp2IL.Plugin.ControlFlowGraph, which shows the shape that work is taking.

Installing Cpp2IL and running it on a game folder

The README says the information it gives applies to the CLI application available on GitHub releases. There is no package manager install documented for the CLI itself; you get the executable from the releases page. The simplest case is a Windows x86 or x64 Unity game, where Cpp2IL detects the Unity version, locates the files it needs, and dumps output into a cpp2il_out folder in the directory you ran the command from.

Cpp2IL-Win.exe --game-path=C:\Path\To\Your\Game

After it finishes, look for cpp2il_out next to where you invoked the binary. If auto detection picks the wrong executable because the game directory contains several, the README gives --exe-name for naming the game's exe file explicitly. If you have a single APK file rather than an APKM, and you are on at least Cpp2IL 2021.4.0, the README says you can pass the APK path to the same argument and Cpp2IL will extract what it needs from it.

On the development branch the option surface has changed. Analysis is off by default on this branch and is enabled with --output-as dll_il_recovery. Processing layers such as attributeinjector, which replaces the old --supress-attributes option, are selected with --use-processor and can be repeated. Layer-specific settings go through --processor-config using key=value pairs, documented by whichever plugin provides the layer. The README lists --list-processors and --list-output-formats as commands that list the available layers and formats, and output formats are selected with --output-as.

The decompiled output is messy, and the branch is a rewrite

The README states directly that the decompiled CIL is pretty messy right now, and that most of the time it is at least possible to see what a method does. That is the honest ceiling. The next planned step is pattern matching to convert IL2CPP-specific constructs into C#, with generic ISIL becoming more C#-specific ISIL and new instructions for object creation and throws. Until that lands, expect output that needs a forgiving decompiler. The project's own recommendation is ILSpy over dnSpy because it copes with broken CIL better.

The development branch is explicitly work in progress and subject to change. The CLI was simplified from many options into output formats and processing layers, and the README warns that many of those formats and layers are not yet implemented, so functionality is limited compared with previously released versions. Options including --analysis-level and --skip-analysis were removed. Metadata dumps and method dumps are now separate output formats rather than both being on by default, which means running Cpp2IL more than once if you want both. The README says that may change.

Release cadence is slow and the version numbers are misleading. The most recent release listed is 2022.1.0-pre-release.21 from 2026-02-22, preceded by .20 in 2025-08-11 and .19 in 2024-12-08. A 2022 version string does not mean 2022 code. The repository's last push was on 2026-09-15, so development is ongoing even though tagged previews appear roughly once or twice a year. If your workflow needs a pinned, stable release, the preview numbering should give you pause.

Where Cpp2IL is the wrong tool

The clearest failure mode is a target that is not IL2CPP. Mono builds do not produce the metadata structures LibCpp2IL parses, so there is nothing for Cpp2IL to reconstruct. If you are not sure which backend a game uses, check before spending time on the tool.

Obfuscated or encrypted metadata and binaries are the second boundary. The README lists support for loading those as something the plugin system will eventually provide, which places it in the future rather than the present. Treat a heavily protected target as out of scope until that work is documented.

The third boundary is output quality. Cpp2IL reconstructs DLLs; it does not produce readable C#. If your goal is to understand a method's logic at a glance, the round trip through ISIL and back to CIL will hand you something you still have to decompile and read carefully. The README's own framing, that the decompiled CIL is messy, should be taken at face value rather than as modesty. And on the development branch, a format or layer you need may simply not exist yet, since the README says many are unimplemented.

Cpp2IL against ILSpy and dnSpy

ILSpy and dnSpy are .NET decompilers: you point them at a managed assembly and they show you C#. They are not alternatives to Cpp2IL for an IL2CPP build, because there is no managed assembly to open until something recreates one. That is the gap Cpp2IL fills. The relationship is sequential rather than competitive, and the README makes it explicit by recommending ILSpy as the tool to open Cpp2IL's output, on the grounds that it handles broken CIL better than dnSpy.

The genuine alternative is not another decompiler but the parser underneath. LibCpp2IL is available from the build artifacts and carries its own documentation, so a team that only needs metadata, not reconstructed method bodies, can consume that library and skip the ISIL pipeline entirely. That is a smaller dependency and a smaller surface for the rewrite to disturb. For teams that want the full reconstruction, Cpp2IL.Core is the embeddable form, documented separately in README_CORE.md, with the CLI as a wrapper. Choosing between the three comes down to how much of the pipeline you actually need.

Licence, maintenance and what upgrading costs

Cpp2IL is MIT licensed, and LibCpp2IL is released under the same licence, which the README states when pointing at the build artifacts. MIT is permissive and places few conditions on reuse, but this is a description of the licence text, not legal advice; check how the terms apply to your distribution.

The maintenance picture is mixed. The last push to the repository was on 2026-09-15, so work is happening. Tagged releases are another matter: the newest listed is a preview from 2026-02-22, and the two before it are from 2025-08-11 and 2024-12-08. Anyone pinning to a release is choosing between a preview build and the development branch, and the README describes that branch as subject to change.

Upgrade cost is concentrated in the CLI rewrite. If you scripted against the old options, --analysis-level, --skip-analysis and --supress-attributes are gone or replaced. Analysis now requires --output-as dll_il_recovery. Attribute suppression moved to the attributeinjector processing layer selected with --use-processor. Metadata and method dumps are separate output formats, so a pipeline that expected both from one invocation needs two. CI builds for developers come from a separate NuGet feed rather than the main releases, which is where to look if you want to track the branch between previews.

Editorial conclusion

Adopt Cpp2IL if you need to inspect the managed side of an IL2CPP Unity build and you can live with messy decompiled CIL; the README itself points users at ILSpy because it handles broken CIL better than dnSpy. Do not adopt it if you need a stable, fully documented CLI: the development branch is a rewrite, analysis is off by default, and metadata and method dumps require separate runs. Before relying on it, verify that your Unity version is detected, that --list-output-formats shows the format you need, and that the output opens in ILSpy.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. SamboyCoding/Cpp2IL on GitHub