Set up Lumafly and install your first Hollow Knight mods

Hollow Knight has no official mod support, but the community built an installer that makes the whole process a few clicks: it patches the game with the Modding API, shows you a catalogue, and handles updates. This guide installs Lumafly, enables the API, installs a first mod, and explains where the files actually go so you can fix things when the installer cannot.

It covers the Windows Steam and GOG versions. Mac and Linux work with the same tools but use different folder paths, noted where they differ.

This is for the original Hollow Knight only. Silksong is a separate game with its own modding tools, and Lumafly deliberately ignores it.

Before you start

• Make sure the game is on the current 1.5 version. Steam and GOG keep it updated automatically. Launch it once so the save folder exists.
• Close the game. The installer cannot patch files while they are in use.
• Know where the game is installed. On Steam: right-click Hollow Knight, Manage, Browse local files.

Install Lumafly

1. Download Lumafly from its GitHub releases page. It is a single executable with no installer of its own.
2. Run it. On first launch it looks for the game automatically. If it cannot find it, point it at the folder that contains hollow_knight.exe.
3. The main window shows an API toggle at the top and a searchable list of mods below it.

If you already have Scarab installed, you do not need both. Lumafly reads the same mod list and picks up mods Scarab installed.

Enable the Modding API

Click the API toggle. Lumafly downloads the patched Assembly-CSharp.dll, backs up the vanilla one as Assembly-CSharp.dll.v next to it, and swaps them. The modded copy is kept as Assembly-CSharp.dll.m, which is how Lumafly can flip between the two without downloading anything again.

Launch the game once. The main menu should now show a Mods entry and the API version in the corner. If you see neither, the patch did not apply; see the gotchas section.

Install your first mod

A good first mod is something visible and low-risk. Benchwarp lets you teleport between benches from the pause menu and does nothing to your save.

1. In Lumafly, type the mod's name into the search box.
2. Click Install. Lumafly also installs any libraries the mod depends on.
3. Launch the game, open the pause menu, and the new option is there.

Every mod in the list follows the same three steps. Mods that add settings appear in the in-game Mods menu, where you can also disable any mod without uninstalling it.

Where the files live

You will eventually want to know this for troubleshooting or for installing a mod that is not in the catalogue.

• Windows: Hollow Knight\hollow_knight_Data\Managed\Mods\
• macOS: Hollow Knight.app/Contents/Resources/Data/Managed/Mods/
• Linux: Hollow Knight/hollow_knight_Data/Managed/Mods/

Each mod is a folder containing a .dll and sometimes a README or asset files. To install a mod manually, create a folder with the mod's name and drop the .dll inside. To remove one, delete the folder. Lumafly also has a Disabled folder alongside it where toggled-off mods are parked.

The API writes a log at %USERPROFILE%\AppData\LocalLow\Team Cherry\Hollow Knight\ModLog.txt. When a mod misbehaves, this file names it.

Play vanilla again

Toggle the API off in Lumafly. It restores the vanilla Assembly-CSharp.dll and the Mods menu disappears. Your mods stay on disk for when you toggle it back on. This is also the right move before reporting a bug to Team Cherry, since they will ask whether the game was modded.

When the Mods menu or a mod misbehaves

• No Mods menu after enabling the API. Usually the game was running during the patch, or Steam verified files and reverted the change. Close the game, toggle the API off and on again.
• Game crashes on the Team Cherry logo. A mod is out of date for the current API. Open ModLog.txt, find the mod named in the last error, and disable it.
• A mod says it is missing a dependency. Install through Lumafly rather than manually; it resolves libraries like Satchel and SFCore automatically.
• Randomizer saves look broken in vanilla. Expected. Keep separate save slots for modded and vanilla play, and back up the saves folder before installing a randomizer.
• Steam Deck or Linux install not detected. Point Lumafly at the game folder manually. Proton installs live under steamapps/common/Hollow Knight/.
• Antivirus quarantines Lumafly or the API. Both patch a game executable's assemblies, which some scanners flag. Download only from the official GitHub releases and whitelist the game folder.

Writing your own mod

Mods are C# class libraries built against the patched game assembly. The Modding API repository is the place to start: it holds the API source and a set of example mods you can build and load as a first test. Put your compiled .dll in its own folder under Mods, launch the game, and ModLog.txt will tell you whether it loaded.