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 MethodBuilder backend of DynamicMethodDefinition only exists in the .NET Framework builds and the net9.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 /tmp by default. If your system forbids loading executables from /tmp, set the HelperDropPath switch.

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.

See Also