01When to use Import local mod
Open Settings → Profile and press Import local mod, the button under that same heading. It covers two situations: a package that is not on Thunderstore at all, and a session where Thunderstore cannot be reached while you already hold the archive. It is not a shortcut for normal installs, because a package taken from the Online tab gains a version record, dependency resolution and update notices that a local import will never have. Import into a dedicated profile so the local file stays out of a setup you can rebuild entirely from Thunderstore, and keep that profile for anything you added by hand.
02Name the file so the import resolves
Without a manifest, the manager infers metadata from the file name. Three patterns are recognised: Author-ModName-Version, ModName-Version, and ModName on its own, with hyphens replaceable by underscores. The author name matters beyond labelling, because it is what resolves the import against a future Thunderstore upload; if a published release carries a higher version than the one you imported, users are prompted that an update is available. A name with no author still imports, but the package can never be matched to a store release later. Rename the archive before importing rather than after, because the name is read once at import time.
03Use manifest.json for dependencies
A manifest.json in the root of the zip is read using Thunderstore's V1 format, which is what lets you supply dependencies, a description and other metadata a file name cannot carry. The limitation is the author: the published V1 specification has no author field, so the file name conventions still apply for that part. The file has to sit at the root of the archive rather than inside a subfolder, and it must be valid JSON, because a malformed manifest falls back to name-based inference. A description also makes the package identifiable in the Installed tab instead of a bare file name.
04Add the author field for early access
Adding an author entry to that manifest, a key named author with the author name as its value, improves things further: the file name conventions can then be ignored entirely, because everything the manager needs is inside the manifest. This is the recommended approach for distributing early-access builds, and it is the right one if the package is intended to reach Thunderstore later under the same author. The published V1 specification does not define the field, so it is an addition on top of that format rather than part of it.
05Understand the deprecated V2 format
A second manifest format, V2, was originally intended as Thunderstore's successor to V1, but the required information has changed since it was proposed and it has been deprecated for imports. It still works for r2modman. Its field names are case sensitive and must match exactly: ManifestVersion, AuthorName, Name, DisplayName, Version, Dependencies, OptionalDependencies, InstallMode, Loaders and the rest, and a missing or misspelled field can break the import. New packages should use V1 with an author field; V2 is worth knowing because older zips still ship with it, so follow the current V1 template rather than copying an old V2 file.
06Verify through the loader log
Import into a profile that contains only the loader and the dependencies the mod needs, then launch with Start modded. For the log, open Settings → Debugging and press Copy log to clipboard, or open BepInEx/LogOutput.log inside the profile folder you reach from Settings → Directories → Data and profile folders → Profile folder → Browse. Confirm the plugin appears by name and note the first exception if one is thrown, because later lines usually describe the consequences of the first failure rather than its cause. A locally imported package receives no dependency resolution, so satisfy its prerequisites from the Online tab before testing it. If nothing shows up in the log at all, the archive structure or the loader is at fault rather than the plugin.
07Shorten the developer loop with symlinks
Once a package is imported you do not have to re-import on every build. Open Settings → Directories → Data and profile folders, press Browse on the Profile folder row, and go to the plugin directory, usually /BepInEx/plugins/<Author-ModName>/. Replace the DLL and assets there with symbolic links pointing at your build output, and each rebuild is picked up without touching the manager. The profile still lists the package by name and version while the files on disk come from your development tree, so the Installed tab stays readable through a long debugging session. Remove the symlink and re-import when you want to test the packaged build.
08Share local mods responsibly
Local content does not travel with a profile. Manually installed and locally imported mods are not installed when someone imports your export, and choosing update existing profile removes them from the target entirely. A profile code tells the recipient which packages to fetch; it cannot hand over a binary that was never published. Send the archive separately with installation notes naming the loader, the dependency versions and the source commit, and only when the author's licence permits redistribution. r2modman cannot track updates for an unpublished build, so check the source you built from.
✦ Frequently asked questions
Common questions, answered directly.
Will a local zip install its own dependencies?
Not reliably. A manifest can declare them, but a plain DLL or an archive with no manifest leaves dependency resolution to you. Install the loader and each required library from the Online tab first, then import the local file and launch.
Why did my import ignore the manifest?
Check the archive layout. A manifest.json has to sit at the top level of the zip to be read; nested inside a folder it is skipped and the manager falls back to file name conventions. A malformed JSON file is ignored in the same way.
Do local mods travel in a shared profile export?
No. Manually installed and locally imported mods are not installed when a profile is imported, and importing over an existing profile removes them. Anyone who needs the file must receive it separately with instructions, and only within the terms of its licence.
How do I update a local mod?
Re-import the new build, or replace the DLL in the profile's plugin folder, usually /BepInEx/plugins/<Author-ModName>/, with a symlink to your build output so rebuilds are picked up automatically. r2modman cannot detect updates for a package that is not published, so track the source you built it from.
Can a local import be replaced by a Thunderstore release later?
Yes, if the author name matches. Once the package is published and its release version is higher than the imported one, everyone is prompted that an update is available. Use the same author name in the manifest so the import resolves to the published package.
Each step on this page ends in a result you can see before the next one starts, so a failure points at one layer instead of the whole stack.
Next: download or update the current build, keep one profile with only the loader enabled, confirm a modded launch from Start modded, then add the rest of your mods in small batches.