Harmony 2.4: patching .NET and Mono methods at runtime

Two NuGet packages decide how much control you keep

The installation decision is a single choice between two packages, and the project is explicit about which one it prefers. Lib.Harmony is a single file, dependency-merged assembly, and it is described as the preferred way. Lib.Harmony.Thin is for the case where you supply the dependencies yourself: you get more control, and in exchange you are responsible for making all references available at runtime. That trade is the whole story. The merged build is one thing to ship into a mod folder; the Thin build is one thing to reason about when a dependency version collides with what the host already loaded. A third package directory, Lib.Harmony.Ref, sits in the tree without being described in the README, so treat its role as undocumented.

Lib.Harmony
Lib.Harmony.Thin

Keeping the original method is the whole difference

Other patch libraries simply let you replace the original method. Harmony's pitch is the set of things beyond that. It keeps the original method intact instead of overwriting it. It runs your code before and/or after the original method rather than instead of it. It modifies the original with IL code processors. Multiple Harmony patches coexist and do not conflict with each other, which is what makes several mods from different authors work on one host. And it works at runtime without touching any files, so there is no patched build to distribute and no original binary to checksum. For a game mod ecosystem that is the difference between shipping a mod and shipping a fork. The README does not document how conflicts between two patches touching the same IL are actually resolved.

It expects your code to arrive as a module or plugin

There is a precondition, and it decides whether Harmony applies to you at all: if you develop in C# and your code is loaded as a module or plugin into a host application, you can use Harmony to alter the functionality of all the available assemblies of that application. That is a runtime hook, not a build step and not a source transformer. It means the surface is whatever the host has already loaded, and the target has to be running before you can touch it. The README states that scope in one sentence and does not extend it: there is no discussion of patching a standalone executable with no plugin entry point, no mention of ahead-of-time compiled or trimmed builds, and no list of runtimes beyond .NET and Mono. Those questions have to be answered by trying it, not by reading.

master is Harmony 2.x, and Infix patching is on v3

The branch layout splits the library in two, and the split is deliberate rather than accidental. The master branch maintains Harmony 2.x. Harmony 3 development, including Infix patching, is on the v3 branch. That means a feature described as an Infix patch is not something you will find in the 2.x line, and reading v3 documentation while targeting 2.x is a mistake the README warns about indirectly by separating the branches. The most recent releases listed are Harmony 3 release candidates: v3.0.0-rc.4 on 2026-10-30, v3.0.0-rc.3 on 2026-10-15 and v3.0.0-rc.2 on 2026-10-11. The repository is not archived and its last push was on 2026-10-30.

Version 2.4
v1.2.0.1
https://harmony.pardeike.net

Harmony 1.x and 2.x must not be mixed

The deprecation notice is the part to read twice, because it is stated as a hard boundary. Harmony 1 is deprecated and not under active development anymore. Its latest version, v1.2.0.1, is described as stable and containing only minor bugs, and the advice is to keep using it if you are in an environment that exclusively uses Harmony 1. Then the warning: Harmony 1.x and 2.x are not compatible with each other and should not be mixed. In practice that warning is aimed at mod authors, because the host application is what decides which line is already loaded. If a game or tool you are modding ships its own Harmony 1, a mod compiled against 2.x does not degrade gracefully, and the old API documentation still living in the project wiki makes it easy to write against the wrong version by accident.

MonoMod.Core comes from another project, and is vendored too

The README credits MonoMod.Core, by 0x0ade and nike4613, as the library the project builds on. Reading the repository layout, that dependency is not only consumed as a package: there is a .gitmodules file, a LocalMonoMod directory, a packages/ directory, Directory.Build.props, Directory.Build.targets and a global.json. Together those suggest the MonoMod sources are also vendored so a local build does not depend on fetching them. The practical consequence for you is version coupling. The README names no MonoMod.Core version and does not say which of the two Harmony distributions carries it, so when you choose the Thin package you are choosing more control over exactly the dependency whose version the README does not state.

Thirteen named titles, and no API reference in the README

The adoption list is the strongest evidence here, and it is worth reading as evidence of use rather than as a support list. Named titles include Rust, Rimworld, 7 Days To Die, Stardew Valley, Subnautica, Oxygen Not Included, Besiege, Cities: Skylines, Kerbal Space Program, Resonite, BattleTech and Slime Rancher, with Ravenfield, Sheltered, Staxel, Total Miner, Unturned and SCP: Secret Laboratory added as others, and Genshin Impact Miliastra Wonderland in the main block. The same tooling is used in unit testing WPF controls at Microsoft and Google, which is a different kind of deployment and a decent argument that the patching layer is not game-specific. What the README does not contain is any API reference. Documentation lives at harmony.pardeike.net, and the wiki is described as the old Harmony 1 pages.

Editorial conclusion

Adopt Harmony 2.x if you write a C# mod or plugin that loads into a host application and need the original method to keep running, which is the thing that separates it from a replace-only patcher. Leave it alone if your environment is pinned to Harmony 1, because the two lines are not compatible with each other, or if you need Infix patching, which lives on the v3 branch. Verify three things before writing a patch: which Harmony version your host application already ships, whether you want the merged Lib.Harmony assembly or the Thin package you supply yourself, and whether the API you have read about exists on master or only on v3.

Frequently asked questions

Official sources

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