Installation
This page lists MonoMod's NuGet packages, the target frameworks they are built for, the runtimes and platforms the detour engine supports, and how to obtain the command-line tools. It ends with a short verification program and installation troubleshooting.
Packages
The libraries are published to NuGet under these package IDs (taken from the project files):
| Package | Depends on | Use it for |
|---|---|---|
MonoMod.RuntimeDetour |
MonoMod.Core, MonoMod.Utils, Mono.Cecil |
Hook, ILHook, NativeHook, DetourConfig, DetourManager. Start here. |
MonoMod.Utils |
Mono.Cecil, MonoMod.Backports, MonoMod.ILHelpers |
ILCursor, DynamicMethodDefinition, DynamicData, ModInterop, PlatformDetection, DynDll, Switches, DebugLog. |
MonoMod.Core |
MonoMod.Utils, Mono.Cecil |
The raw detour engine (DetourFactory, PlatformTriple). Only for library authors building their own hooking layer. |
Install with the .NET CLI:
dotnet add package MonoMod.RuntimeDetour
or only the utilities:
dotnet add package MonoMod.Utils
or with a PackageReference in your project file (pick the version you want from NuGet; the source tree is at 25.4.0 for RuntimeDetour):
<ItemGroup>
<PackageReference Include="MonoMod.RuntimeDetour" Version="25.4.0" />
</ItemGroup>
MonoMod.RuntimeDetour brings in MonoMod.Core and MonoMod.Utils transitively, so you do not need to reference them separately.
Mono.Cecil Version
MonoMod.Utils declares a dependency range of Mono.Cecil [0.10.0,0.11]. The build itself uses Cecil 0.11.6 for modern targets and 0.10.4 for some older ones (tools/Common.CS.props). If your application, or a game it mods, already ships a specific Cecil version, make sure it falls in that range.
Target Frameworks
The shared build properties (tools/Common.props) multi-target every library at:
| Family | Target frameworks |
|---|---|
| .NET Framework | net35, net452 |
| .NET Standard | netstandard2.0, netstandard2.1 |
| .NET | net5.0, net6.0, net7.0, net8.0, net9.0, net10.0, net11.0 |
NuGet picks the closest match for your project automatically. net35 support is what lets MonoMod run inside old Unity games.
A few features depend on the target framework the library was compiled for:
- The
MethodBuilderbackend ofDynamicMethodDefinitiononly exists in the .NET Framework builds and thenet9.0-and-newer builds. - Runtime-async handling is only relevant on runtimes that implement that feature.
Supported Platforms
The detour engine (MonoMod.Core) selects one implementation per architecture, operating system, and runtime (the "platform triple"). The selection code in PlatformTriple.cs and CoreBaseRuntime.cs gives this support matrix:
| Dimension | Supported | Not supported (what happens) |
|---|---|---|
| Architecture | x86, x86_64 (AMD64), ARM64 | 32-bit ARM: NotImplementedException |
| Operating system | Windows (including Wine), Linux, macOS | Android, iOS, BSD, generic POSIX: NotImplementedException |
| Runtime | .NET Framework (CLR 2 and CLR 4), Mono, CoreCLR | Anything else: PlatformNotSupportedException |
| CoreCLR versions | .NET Core 2.x, 3.0, 3.1, .NET 5, 6, 7, 8, 9, 10, 11 | Any other major version: PlatformNotSupportedException("CoreCLR version {version} is not supported"). New versions must be added manually. |
MonoMod.Utils on its own works more widely, because most of it does not touch machine code.
Note: On Unix-like systems, MonoMod.Core writes a small native helper library to disk and loads it (to handle exceptions crossing its JIT hook, and on Apple Silicon to patch JIT-executable memory). It is dropped into
/tmpby default. If your system forbids loading executables from/tmp, set theHelperDropPathswitch.
Getting the Command-Line Tools
MonoMod.Patcher (the MonoMod executable), MonoMod.RuntimeDetour.HookGen and MonoMod.DebugIL are console applications (OutputType Exe). In the current source tree all three set IsPackable to false, so you get them by building the repository:
git clone https://github.com/MonoMod/MonoMod.git
cd MonoMod
dotnet build -c Release
The repository's README also links to build artifacts produced by its CI workflow for the latest commit. See Contributing for build requirements (the repository pins a .NET 11 SDK in global.json).
Each tool needs MonoMod.Utils.dll, Mono.Cecil.dll (and its companion assemblies), and for HookGen also MonoMod.RuntimeDetour.dll and MonoMod.Patcher.dll next to it.
Verify the Installation
Create a console app, add MonoMod.RuntimeDetour, and run:
using System;
using System.Runtime.CompilerServices;
using MonoMod.RuntimeDetour;
using MonoMod.Utils;
public static class Program
{
[MethodImpl(MethodImplOptions.NoInlining)]
public static int Answer() => 1;
public static void Main()
{
Console.WriteLine($"{PlatformDetection.Runtime} {PlatformDetection.RuntimeVersion} " +
$"on {PlatformDetection.OS} / {PlatformDetection.Architecture}");
using (new Hook(typeof(Program).GetMethod(nameof(Answer))!, new Func<int>(() => 42)))
{
Console.WriteLine(Answer());
}
Console.WriteLine(Answer());
}
}
On 64-bit Windows with .NET 8 the output is similar to:
CoreCLR 8.0.x on Windows / x86_64
42
1
If the first line prints and the program then throws PlatformNotSupportedException or NotImplementedException, your platform is outside the support matrix above.
Troubleshooting Installation
| Symptom | Cause | Fix |
|---|---|---|
FileNotFoundException for Mono.Cecil or MonoMod.Backports at runtime |
The dependent DLLs were not copied next to your mod (common when a game loads mods manually). | Ship every DLL from the package's dependency graph with your mod, or rely on the mod loader's copy. |
Version conflict on Mono.Cecil |
Another component uses Cecil outside [0.10.0,0.11]. |
Align on a Cecil version inside the range. |
PlatformNotSupportedException: CoreCLR version ... is not supported |
The process runs on a .NET major version MonoMod does not know yet. | Use a MonoMod version that supports that runtime, or run on a supported one. |
| Native helper fails to load on Linux/macOS | /tmp is mounted noexec or similar. |
Set MONOMOD_HelperDropPath to a directory you can load code from. See Switches. |