BepInEx: a plugin framework for Unity Mono, IL2CPP and .NET games

What BepInEx solves for Unity and XNA modders

Unity games ship as compiled assemblies, and a modder who wants to change behaviour usually has two bad options: edit the shipped assembly, or ask the developer for a hook. BepInEx takes a third path. It is described as a plugin and modding framework for Unity Mono, IL2CPP and .NET framework games, with XNA, FNA and MonoGame named as examples of the .NET side. The framework loads before the game's own code runs, then hands control to plugins that can patch methods at runtime.

The audience is narrower than "anyone who wants to mod a game". It is people who are comfortable dropping files into a game directory and, for anything beyond installing other people's mods, writing C# against a loader API. The README points plugin authors at the user and developer guides at docs.bepinex.dev rather than documenting the plugin API inline. That split matters: this repository is the loader, not a mod catalogue, and it does not ship gameplay mods of its own.

How the loader, preloader and patchers fit together

The repository layout shows the split directly. BepInEx.Core holds the plugin-facing framework, BepInEx.Preloader.Core holds the code that runs before the game's managed entry point, and Runtimes/ holds the per-runtime pieces. The preloader is the reason BepInEx can work on games that were never designed to be extended: it gets loaded into the process early, then the core takes over once the runtime is up.

Four libraries do the heavy lifting, and the README pins their versions. UnityDoorstop v4.5.0 is the injection mechanism on the Unity side. HarmonyX v2.10.2 provides runtime method patching, and MonoMod v22.7.31.1 sits underneath it. jbevain/cecil v0.10.4 handles assembly reading. For IL2CPP the dependency set changes: Cpp2IL v2022.1.0, Il2CppInterop v1.5.3 and a BepInEx-published dotnet-runtime v6.0.7. That IL2CPP path is structurally different work, which is why it is the less mature half of the project.

Plugins are not the only extension point. The README lists a separate category of plugin loaders, adapters that let BepInEx host mods written for another framework: BSIPA, IPA, MelonLoader, MonoMod, MuseDashModLoader, Partiality, Sybaris, UnityInjector, Unity Mod Manager and uMod each have a linked loader project. If a game's existing mod scene already standardised on one of those, the adapter is what lets BepInEx sit underneath it instead of replacing it.

Installing BepInEx and loading a first plugin

The README does not carry install commands. It links to the installation guide at docs.bepinex.dev/articles/user_guide/installation/index.html for the latest releases, and to the master-branch version of the same guide for BepInEx 6 bleeding-edge builds. Follow those pages for your game and platform; the exact archive name and target directory depend on the game's runtime and architecture, and the README does not spell them out.

The general shape, as the documentation describes it, is that you extract the BepInEx archive into the game's own folder, next to the game executable, and then launch the game once. That first launch is what creates the framework's working directories. Plugin authors and mod packagers distribute plugins that go into the plugins folder inside that structure, which is why the install guide is the entry point rather than any command in this repository.

If you are building BepInEx from source rather than downloading a release, the repository root carries build scripts for each platform. The README does not document them; they appear only as top-level entries in the repository:

build.sh

build.ps1

build.cmd

Those files sit alongside BepInEx.sln at the repository root. This is a contributor workflow, not the normal way to mod a game: for that, use the release archives from the releases page or the bleeding-edge builds site named in the README.

IL2CPP support is the weak half of the compatibility chart

The README states plainly that only Unity Mono has stable releases. The platform chart backs that up with holes. Unity Mono is marked supported on Windows, OSX and Linux, with ARM listed as N/A. Unity IL2CPP is marked supported on Windows and Linux, not supported on OSX, and N/A on ARM. The .NET and XNA row shows Windows, with Mono on OSX and Linux.

Read that chart before choosing a game. A macOS IL2CPP game is outside the supported matrix, and the README does not describe a workaround. ARM is N/A across every row, which rules out the framework for ARM targets as documented. And the stable-release caveat means an IL2CPP user is, by the project's own description, working with something less settled than the Mono path, even though the IL2CPP toolchain is listed with pinned versions.

The other failure mode is quieter. BepInEx patches managed code at runtime, so a game that has been rebuilt with a different runtime, obfuscated differently, or updated past the point where a plugin's target methods still exist will load the framework and then fail inside a plugin. Nothing in this repository guarantees that a plugin keeps working across game updates; that is the plugin author's problem, and the loader's job ends at getting the plugin loaded.

BepInEx compared with MelonLoader and per-game loaders

MelonLoader is the closest comparable project, and the difference is architectural rather than cosmetic. MelonLoader is itself a mod loader with its own plugin API. BepInEx treats that as one more thing to host: the README lists BepInEx.MelonLoader.Loader as an available plugin loader, so BepInEx can run MelonLoader-style mods through an adapter instead of competing for the same plugin folder. That adapter approach is the distinguishing design decision here. BepInEx positions itself as a base layer that absorbs other loaders, which is why the list includes IPA, BSIPA, Partiality, Sybaris, UnityInjector, Unity Mod Manager and uMod alongside MelonLoader.

The trade-off is indirection. Every adapter is another moving part between the game and the mod, and the README does not document how faithfully each adapter reproduces its original loader's behaviour. A game with an established mod scene on one of those frameworks may be better served by that framework directly, especially if the scene's tooling assumes it. BepInEx earns its place when you want one loader across several games, or when you are writing your own plugins and want the HarmonyX and MonoMod patching stack rather than a bespoke hook system.

Maintenance, licensing and what upgrading costs you

The repository is not archived, and the last push was on 2026-09-20. Release cadence on the 5.x line has been roughly one release every four to eight months: v5.4.23.3 on 2025-04-22, v5.4.23.4 on 2025-09-25, and v5.4.23.5 on 2026-02-08. Those are patch-level version bumps, which suggests the 5.x line is in maintenance rather than feature development, while BepInEx 6 lives on the bleeding-edge builds site the README links.

That split is the upgrade question. The README points to two separate installation guides, one for latest releases and one for BepInEx 6 bleeding-edge builds, and describes only Unity Mono as having stable releases. Moving a plugin from 5.x to the 6 line means moving to builds the project does not label stable, and the IL2CPP toolchain versions pinned in the README (Cpp2IL v2022.1.0, Il2CppInterop v1.5.3) are the ones that path depends on.

Licensing: the project is LGPL-2.1, and the LICENSE file is at the repository root. The README states the licence in one line and says nothing about what it means for mod distribution or for bundling the framework with a game. This article is not legal advice; if you plan to redistribute BepInEx inside a packaged build, read LICENSE and the licences of the bundled libraries, several of which are separate projects with their own terms.

Editorial conclusion

Adopt BepInEx when the target game runs Unity Mono and you want plugin loading that does not require editing the game's own assemblies by hand. Skip it if the game is IL2CPP on macOS, since the compatibility chart marks that combination unsupported, or if you need a stable IL2CPP release, because the README says only Unity Mono has stable releases. Before committing, open the installation guide at docs.bepinex.dev for your release line, confirm which loader your target game's existing mods expect, and check the bleeding-edge build page if you need BepInEx 6. The LGPL-2.1 licence governs the framework itself, so read LICENSE before redistributing it inside a game bundle.

Frequently asked questions

Official sources

1. BepInEx/BepInEx on GitHub
2. Issues
3. License: LGPL-2.1
4. README
5. Releases