fabric.mod.json 26.1.2

A guide to the fabric.mod.json specification.

WARNING

This page is written for version 26.1.2. Documentation for older versions may be incomplete.

The fabric.mod.json file is a metadata file used by Fabric Loader to load mods. It must be placed in the JAR's root directory for the mod to get loaded.

A predefined fabric.mod.json file is included in the template mod, or it can be generated by Fabric Loom.

You can consult the source code of the specification for fabric.mod.json v1. You will also find the fabric.mod.json file used by this website's Example Mod below.

fabric.mod.json of the Example Mod

{
  "schemaVersion": 1,
  "id": "example-mod",
  "version": "1.0.0",
  "name": "Example Mod",
  "icon": "assets/example-mod/icon.png",
  "environment": "*",
  "entrypoints": {
    "main": [
      "com.example.docs.ExampleMod",
      "com.example.docs.event.ExampleModEvents",
      "com.example.docs.command.ExampleModCommands",
      "com.example.docs.effect.ExampleModEffects",
      "com.example.docs.potion.ExampleModPotions",
      "com.example.docs.sound.ExampleModSounds",
      "com.example.docs.damage.ExampleModDamageTypes",
      "com.example.docs.item.ExampleModItems",
      "com.example.docs.enchantment.ExampleModEnchantments",
      "com.example.docs.block.ExampleModBlocks",
      "com.example.docs.block.entity.ExampleModBlockEntities",
      "com.example.docs.menu.ExampleModMenuType",
      "com.example.docs.component.ExampleModComponents",
      "com.example.docs.advancement.ExampleModDatagenAdvancement",
      "com.example.docs.networking.ExampleModNetworking",
      "com.example.docs.networking.basic.ExampleModNetworkingBasic",
      "com.example.docs.debug.ExampleModDebug",
      "com.example.docs.saveddata.ExampleModSavedData",
      "com.example.docs.entity.attribute.ExampleModAttributes",
      "com.example.docs.recipe.ExampleModRecipes",
      "com.example.docs.entity.ExampleModEntity",
      "com.example.docs.gamerule.ExampleModGameRules",
      "com.example.docs.conditions.ExampleModResourceConditions",
      "com.example.docs.stats.ExampleModStats"
    ],
    "client": [
      "com.example.docs.client.command.ExampleModClientCommands",
      "com.example.docs.ExampleModBlockEntityRenderer",
      "com.example.docs.ExampleModDynamicSound",
      "com.example.docs.ExampleModClient",
      "com.example.docs.ExampleModScreens",
      "com.example.docs.rendering.CustomRenderPipeline",
      "com.example.docs.rendering.HudRenderingEntrypoint",
      "com.example.docs.rendering.RenderingConceptsEntrypoint",
      "com.example.docs.network.basic.ExampleModNetworkingBasicClient",
      "com.example.docs.appearance.ExampleModAppearanceClient",
      "com.example.docs.keymapping.ExampleModKeyMappingsClient",
      "com.example.docs.ExampleModRecipesClient",
      "com.example.docs.entity.ExampleModCustomEntityClient"
    ],
    "fabric-datagen": ["com.example.docs.datagen.ExampleModDataGenerator"]
  },
  "mixins": [
    "example-mod.mixins.json",
    {
      "config": "example-mod.client.mixins.json",
      "environment": "client"
    }
  ],
  "depends": {
    "fabricloader": ">=0.19.0",
    "minecraft": "~26.1",
    "java": ">=25",
    "fabric-api": "*"
  },
  "accessWidener": "example-mod.classtweaker"
}

Mandatory Fields

The following fields are mandatory for Fabric to load your mod.

• schemaVersion Must be the first entry, and the value must always be 1. Required for Fabric Loader to parse the file correctly.
• id A string value that defines the mod's identifier. Must start with a letter. May only contain ASCII letters, digits, underscores, or hyphens. 2 to 64 characters.
• version A string value that defines the mod's version; it should preferably match a superset of the Semantic Versioning 2.0.0 specification, supporting any number of components, and arbitrary build metadata. If it does not match that, it is treated as a plain string, with no support for version ranges.

"schemaVersion": 1,
"id": "example-mod",
"version": "1.0.0"

Metadata

• name: A string that defines the user-friendly mod name. If not present, defaults to the id.
• description: A string that defines the mod's description. If not present, defaults to an empty string.

"name": "Example Mod",
"description": "This is an example description! Tell everyone what your mod is about!",

Contact

contact: A dictionary that defines the contact information for the project. Some common fields include:

• email: A string that defines the contact e-mail pertaining to the mod. Must be a valid e-mail address.
• homepage: A string that defines the project or user's homepage. Must be a valid HTTP/HTTPS address.
• irc: A string that defines the IRC channel pertaining to the mod. Must be of a valid URL format - for example: irc://irc.esper.net:6667/charset for #charset at EsperNet - the port is optional, and assumed to be 6667 if not present.
• issues: A string that defines the project's issue tracker. Must be a valid HTTP/HTTPS address.
• sources: A string that defines the project's source code repository. Must be a valid URL - it can, however, be a specialized URL for a given VCS (such as Git or Mercurial).

The list is not exhaustive - mods may provide additional non-standard keys, such as discord, slack, twitter... If possible, those should be valid URLs.

"contact": {
    "homepage": "https://fabricmc.net",
    "sources": "https://github.com/FabricMC/fabric-example-mod"
}

Authors and Contributors

• authors An array of authors of the mod. Entries can be either a string or an object with the fields listed below.
• contributors An array of contributors to the mod. Entries can be either a string or an object with the fields listed below.

Fields:

• name A mandatory string for the person's real name, or username.
• contact An optional object for the person's contact information. The same as upper level contact.

"authors": [
    "Me!",
    {
        "name": "Tiny Potato",
        "contact": {
          "homepage": "https://fabricmc.net",
          "sources": "https://github.com/FabricMC/fabric-example-mod"
        }
    }
]

License

• license A string or array that defines the licensing information. To aid automated tools, it is recommended to use SPDX License Identifiers for open-source licenses.

This should provide the minimal set of licenses that satisfy the entire mod package. In other words, someone seeking to use or redistribute your mod should only need to comply with the licenses listed here. If parts of your code are dual-licensed, choose the preferred license. This list does not necessarily forbid you from granting additional rights or applying different licenses for certain people on a case-by-case basis.

"license": "CC0-1.0"

Icon

• icon A string or dictionary that defines the mod's icon. Icons are square PNG files. Minecraft resource packs use 128×128, but that is not a hard requirement - a power of two is, however, recommended. Can be provided in one of two forms:
  • A path to a single PNG file.
  • A dictionary of images widths to their files' paths.

"icon": "assets/example-mod/icon.png"

Mod Loading

Environment

• environment: A string value that defines which environments the mod should be run on:
  • *: Runs in all environments. Default.
  • client: Runs on the physical client side. If set, your mod will not be loaded on dedicated servers.
  • server: Runs on the physical server side. If set, your mod will not be loaded on clients, this includes singleplayer and LAN.

"environment": "*"

Entrypoints

• entrypoints An object that defines the main classes that your mod will load.
  • main An array of string class names that implement ModInitializer.
  • client An array of string class names that implement ClientModInitializer. This entrypoint is run after main, and only on the physical client side.
  • server An array of string class names that implement DedicatedServerModInitializer. This entrypoint is run after main, and only on the physical server side.

Fabric Loader provides those three main entrypoints, but other mods may provide their own. For example, Fabric API provides fabric-datagen for data generator entrypoints.

Each entrypoint can load multiple classes, and even methods or static fields. For example:

"main": [
    "net.fabricmc.example.ExampleMod",
    "net.fabricmc.example.ExampleMod::handle"
]

TIP

If you're not using Java, you should consult the language adapter's documentation. For Kotlin, that's in the Fabric Language Kotlin's README.

JARs

• jars: An array of JARs to be nested inside your mod. When using include on your dependencies, Loom will automatically populate this. Each entry is an object containing a file key, with a path to the nested JAR from within your mod's. For example:

"jars": [
   {
      "file": "nested/vendor/dependency.jar"
   }
]

Language Adapters

• languageAdapters: A dictionary of classes that implement LanguageAdapter.

"languageAdapters": {
   "kotlin": "net.fabricmc.language.kotlin.KotlinAdapter"
}

Mixins

• mixins: A list of mixin configuration files. Each entry is either a path to a mixin configuration file within your mod's JAR, or an object containing the following fields:
  • config: The path to the mixin configuration file inside your mod's JAR.
  • environment: Behaves just like the upper level environment field. For example:

"mixins": [
   "example-mod.mixins.json",
   {
      "config": "example-mod.client-mixins.json",
      "environment": "client"
   }
]

Access Wideners

• accessWidener: A string identifying an access widener or class tweaker file.

"accessWidener": "example-mod.classtweaker"

Provides

• provides： An array of mod IDs that will be aliases for the mod. Fabric Loader will treat these IDs as if the respective mods exist. If any other mod uses one of them, it will not be loaded.

"provides": [
   "example_mod"
]

Dependency Resolution

The following keys will accept a dictionary of dependencies. For more details on how to structure the dictionary, see below:

• depends: For dependencies required to run. If any are missing, Fabric Loader will trigger a crash.
• recommends: For dependencies not required to run. For each missing dependency, Fabric Loader will log a warning.
• suggests: For dependencies not required to run. Use this as a kind of metadata.
• breaks: For mods whose together with yours might cause a game crash. If any are present, Fabric Loader will trigger a crash.
• conflicts: For mods whose together with yours cause some kind of bugs, etc. For each conflicting mod present, Fabric Loader will log a warning.

Semantic Versioning

The key of each entry is the mod ID of the dependency.

The value of each key is a string or array of strings declaring supported version ranges of the dependency. If it's an array, only one of the ranges has to match for the constraint to be satisfied.

Fabric uses a superset of Semantic Versioning to support any number of components; for example, versions like 1.2.3.4 are supported. When comparing versions with a different number of components, they are padded on the right with 0; for example, 26.1 = 26.1.0

To match all prerelease components in range, suffix the range with -; for example, to get the 26.2 snapshots only, use the range >26.2- <26.2.

Build metadata, that is whatever follows the + in a version, is ignored for version comparison. E.g. 0.154+26.3 and 0.154+26.2 are equivalent.

Here are some examples of ranges and what they indicate. Try using Outlet's Fabric Loader Verification to test which values will satisfy the constraint.

Semantic Versioning Examples

Note: Minecraft does not abide by semantic versioning. If needed, Fabric will translate a Minecraft version into its equivalent in semantic versioning. Examples include 26.1->26.1.0, 26.1-snapshot-1->26.1-alpha.1, 26w14a->26.1.1-alpha.26.14.a. This pattern changed with the release of 1.16-rc1. Previously, Fabric normalized prereleases like 1.16-pre1 to 1.16-rc.1, which now conflicted. Starting with loader 0.8.8, 1.16-rc1 is normalized to 1.16-rc.9, and future prereleases are normalized to -beta.n.

Range	Description	Matches	Clashes
*	Any version (not recommended)	26.1.2, 24w14potato...	none
26.1.2	Exact version only	26.1.2	26.1, 26.1.1, 26.2...
>26	Above a version (exclusive)	26.1.2, 26.2...	26, 25.x...
>=26.1	At or above a version (inclusive)	26.1, 26.1.2, 26.2...	26.0, 25.x...
<=26.1	At or below a version (inclusive)	26.1, 26.0, 25.x...	26.1.2, 26.2...
>26 <26.2	Between two versions (both exclusive)	26.1, 26.1.2, snapshots...	26, 26.2...
>=26.1 <26.2	Between two versions (inclusive lower bound)	26.1, 26.1.2, snapshots...	26.0, 26.2...
~26.1-rc.2	Same to next minor version, excluding earlier versions (equivalent to >=26.1-rc.2 <26.2-). Only checks the major and minor components.	26.1-rc.2, 26.1, 26.1.2, snapshots...	26.1-rc.1, 26.2, 27.x...
^26.2	Same to next major version, excluding earlier versions (equivalent to >=26.2 <27-). Only checks the major component.	26.2, 26.3...	26.1, 25.x, 27.x...
26.1.x	Equivalent to ~26.1-.	26.1-rc-3, 26.1, 26.1.2, snapshots...	26.2, 27.x...
1.x	Equivalent to ^1-.	1.0.0-beta.4, 1.0.0, snapshots...	26.x
>26.2- <26.2	All snapshots of 26.2, excluding 26.2	26.2-pre-1, 26.2-rc-1	26.2

Note: The .x operator does not work if a prerelease component (e.g. 26.1.x-rc.1) is included; instead, the range is treated as a plain string (See Other Version Formats below). .*, .x, or .X can be used interchangeably. As of Fabric Loader 0.19.3, there is a bug where the .x operator does not work correctly for versions with more than 3 components. This will be fixed in a future version.

Other Version Formats

If a version does not conform to the extended SemVer supported by Fabric, it is treated as a string and compared lexicographically as per Java's String#compareTo for sorting purposes, e.g. during mod loading where Fabric must decide which version to load.

In this mode, the range operators < and > are not allowed. The other range operators behave as =, except for * which will continue to match any version.

See an example of a plain string version.

Note: It is encouraged to use the extended SemVer where possible to support version comparison and ranges!

"depends": {
    "example-mod": "*",
    "minecraft": [
        "26.1",
        "26.1.1"
    ]
}
"suggests": {
    "another-mod": ">1.0.0"
}

Custom Fields

You can add any field you want to add inside custom field. Loader would ignore them. However, it's highly recommended to namespace your fields to avoid conflicts with other mods.