Harmony 2.4: runtime method patching for .NET and Mono

What Harmony solves for plugin developers

Harmony targets a narrow situation: you write C# that is loaded as a module or plugin into a host application, and you need to change what an existing method in that host does. You cannot edit the host, you cannot recompile it, and you may not even have its source. The README frames the library as "an elegant and high level way to alter the functionality in applications written in C#", and lists games such as Rimworld, Stardew Valley, Kerbal Space Program and Cities:Skylines as established users. Microsoft and Google use it in unit testing WPF controls, according to the same README.

The design constraint that separates Harmony from a plain detour library is coexistence. The README claims that multiple Harmony patches can exist on the same method without conflicting, and that the original method stays intact and callable. If you have ever shipped a mod into an ecosystem where three other mods patch the same function, that second property is the one you are buying. A replacement-style patch library forces the last writer to win; Harmony's model lets each patch insert its own code around the original and lets the original still run.

How patching works: prefixes, postfixes and IL processors

The mechanism, as the README describes it, is runtime manipulation of method bodies rather than file rewriting. Harmony works "at runtime and does not touch any files", which matters for games and signed hosts where modifying assemblies on disk would break integrity checks or distribution rules. Under the hood the project credits MonoMod.Core, the library by 0x0ade and nike4613, for the low-level work; Harmony provides the higher-level patching API on top of it.

The README enumerates four capabilities. You can keep the original method intact. You can execute your code before and after the original, which is the prefix and postfix model. You can modify the original with IL code processors. And multiple patches can coexist. The data flow is therefore: your plugin declares a patch against a target method, Harmony applies it to the in-memory method body, and the host application continues running with the altered behaviour. Nothing is written to disk, so the change disappears when the process exits.

One structural detail from the repository layout: the source tree carries a Documentation/ directory and a docs/ directory alongside the solution file, and the README points readers to harmony.pardeike.net rather than reproducing the API surface inline. If you want to know the exact attribute names and signatures for a given release, the README is not the place to look.

Installing Lib.Harmony and applying a first patch

The README gives two installation paths, both NuGet packages, and states a preference. For a single-file assembly with dependencies merged in, use Lib.Harmony; the README calls this the preferred way. If you want to supply dependencies yourself and accept responsibility for making every reference available at runtime, use Lib.Harmony.Thin instead. The repository layout matches this: Lib.Harmony/, Lib.Harmony.Thin/ and Lib.Harmony.Ref/ are all top-level directories, and the README links both packages to their nuget.org pages.

The README does not print an install command, so there is no code block to copy here. What it does give is the package identity: Lib.Harmony for the merged assembly, Lib.Harmony.Thin when you manage the dependencies yourself. Add whichever fits your project through your normal NuGet workflow and make sure the package name matches exactly, since the two packages are not interchangeable at runtime.

After the restore, the assembly is available to your plugin project. The next step is to annotate a patch class and point it at the method you want to alter. The README describes the model as executing your code before and after the original method, which is the prefix and postfix pattern, but it does not print a code sample, so the exact attribute syntax belongs to the documentation site rather than this page. Treat harmony.pardeike.net as the source for the attribute names, the patch method signature rules and the IL processor API on the branch you are targeting.

What you should expect after wiring a patch: the host application runs unmodified on disk, your plugin loads, Harmony applies the patch in memory, and the patched behaviour is visible while the process lives. Restart the host and the original behaviour returns until your plugin loads again.

The Harmony 1 and Harmony 2 split is a real hazard

The clearest limitation in the README is version incompatibility. Harmony 1 is deprecated and, in the README's words, not under active development anymore; version 1.2.0.1 is described as stable with only minor bugs. The stronger statement is that Harmony 1.x and 2.x are "NOT COMPATIBLE" with each other and "SHOULD NOT BE MIXED". The README keeps the old wiki for Harmony 1 documentation.

For a mod author this is not a theoretical concern. If your plugin targets a host whose modding ecosystem still runs Harmony 1, you cannot simply ship a Harmony 2 patch into the same process and expect both to work. You either stay on the environment's version or you require the whole ecosystem to move. The README's advice is to keep using Harmony 1 if you are in an environment that exclusively uses it. That is a maintenance burden the project acknowledges rather than solves.

A second boundary: Harmony 3 development, including something called Infix patching, lives on the v3 branch, and master maintains Harmony 2.x. If you read about Infix patching and then install from the default branch, you are reading about code you do not have. The README is explicit that the two branches are separate.

Harmony compared with plain detouring and source-level hooks

The README positions Harmony against "other patch libraries" that "simply allow you to replace the original method". That is the actual difference in approach. A replacement-style detour hands you the target and expects you to reproduce or discard its behaviour; if two plugins both replace the same method, one of them loses. Harmony instead keeps the original callable and layers your code before or after it, so the ordering problem becomes a coordination problem rather than a last-writer-wins problem.

The trade-off is indirection. Your patch runs inside a pipeline rather than in place of a call, so reasoning about side effects means reasoning about what other patches are doing to the same method. A source-level hook, where you own the code, has none of that ambiguity. If you can edit the host application, you should; Harmony exists precisely because plugin authors usually cannot. The README's own framing supports this: the library is for developers whose code "is loaded as a module/plugin into a host application". Outside that scenario its main advantage disappears.

Licence, maintenance and upgrade cost

Harmony is MIT licensed, per the repository licence field and the LICENSE file at the top level. MIT is permissive, so redistributing the library inside a plugin is generally straightforward, but this is not legal advice and you should read the LICENSE file yourself, particularly if you also redistribute MonoMod.Core, which the README identifies as a separate library by other authors.

The repository is not archived, and the last push was on 2026-09-08. Recent releases are v2.4.0.0, v2.4.1.0 and v2.4.2.0, dated 2025-08-17, 2025-08-22 and 2025-11-13 respectively. That cadence suggests point releases arrive between minor versions rather than on a fixed schedule.

Upgrade cost is dominated by the version split described above, not by API churn between 2.x releases. The repository keeps a HarmonyTests/ directory and a .github/ directory with a test workflow, so the project does test itself, but the README does not document a rollback procedure if a patch breaks a host at runtime. Plan for that gap: since Harmony does not touch files, removing the plugin is the rollback.

Editorial conclusion

Adopt Harmony if you ship a C# plugin loaded into a host application you do not control, and you need several mods to patch the same method without stepping on each other. Do not adopt it if you can edit the host source, or if you need Harmony 1 and Harmony 2 side by side, since the README states the two are not compatible and should not be mixed. Before committing, verify which package fits your deployment (Lib.Harmony merges its dependencies, Lib.Harmony.Thin does not), and check the documentation at harmony.pardeike.net for the patching API on the branch you target, because Harmony 3 work lives on the v3 branch and is not what master ships.

Frequently asked questions

Official sources

1. License: MIT
2. pardeike/Harmony on GitHub
3. Project website
4. README
5. Releases