# How to Install Mods on Your Minecraft Server (/docs/minecraft/mod-setup)



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Files, Folder, File } from 'fumadocs-ui/components/files';

Minecraft mods extend the game with new content — blocks, items, mobs, dimensions, mechanics. Unlike plugins (which run on Bukkit/Spigot/Paper), mods require a dedicated **mod loader** server: **Forge**, **NeoForge**, or **Fabric**.

Mod Loaders [#mod-loaders]

| Loader       | Best For                                            | Key Notes                                                        |
| ------------ | --------------------------------------------------- | ---------------------------------------------------------------- |
| **Forge**    | Largest mod ecosystem (Create, Tinkers, Thaumcraft) | Most popular for modpacks. Supports both legacy and modern mods  |
| **NeoForge** | Modern continuation of Forge                        | Forked from Forge in 2023. Forward-looking API                   |
| **Fabric**   | Lightweight, modern, performance-focused            | Faster updates after game patches. Smaller mod count but growing |

> **Mods are loader-specific.** A Forge mod won't work on Fabric and vice versa. Always check the mod page to confirm the loader.

Mod File Structure [#mod-file-structure]

<Files>
  <Folder name="(server root)" defaultOpen>
    <Folder name="mods" defaultOpen>
      <File name="jei-1.21-forge.jar" />

      <File name="journeymap-1.21-forge.jar" />

      <File name="create-1.21.jar" />

      <File name="fabric-api-1.21.jar" />
    </Folder>

    <Folder name="config">
      <File name="jei.cfg" />

      <File name="create-server.toml" />
    </Folder>
  </Folder>
</Files>

Install Mods [#install-mods]

<Tabs items={['Forge / NeoForge', 'Fabric']}>
  <Tab value="Forge / NeoForge">
    <Steps>
      <Step>
        Switch to Forge or NeoForge [#switch-to-forge-or-neoforge]

        In the [XGamingServer Panel](https://panel.xgamingserver.com), go to **Startup** and select **Forge** or **NeoForge** as the server type. Restart to install the loader. See [Switch Version](/docs/minecraft/switch-version).
      </Step>

      <Step>
        Download mods [#download-mods]

        Get mods from:

        * **[CurseForge](https://www.curseforge.com/minecraft/mc-mods)** — largest mod repository
        * **[Modrinth](https://modrinth.com/mods)** — modern alternative

        Filter by **Forge** (or NeoForge) and your **Minecraft version**.
      </Step>

      <Step>
        Stop the server [#stop-the-server]
      </Step>

      <Step>
        Upload to mods/ [#upload-to-mods]

        Click **Files** in the sidebar and upload `.jar` files to the `mods/` folder.
      </Step>

      <Step>
        Start the server [#start-the-server]

        Watch **Console** for mod loading messages. The server may take longer to start with many mods.
      </Step>
    </Steps>
  </Tab>

  <Tab value="Fabric">
    <Steps>
      <Step>
        Switch to Fabric [#switch-to-fabric]

        In **Startup**, select **Fabric** as the server type. Restart to install.
      </Step>

      <Step>
        Download Fabric API [#download-fabric-api]

        Almost every Fabric mod requires the **Fabric API** (the base library). Download it from [Modrinth](https://modrinth.com/mod/fabric-api) for your Minecraft version.
      </Step>

      <Step>
        Download mods [#download-mods-1]

        Get Fabric-compatible mods from:

        * **[Modrinth](https://modrinth.com/mods?f=fabric)** — filter by Fabric
        * **[CurseForge](https://www.curseforge.com/minecraft/mc-mods)** — filter by Fabric
      </Step>

      <Step>
        Stop the server [#stop-the-server-1]
      </Step>

      <Step>
        Upload to mods/ [#upload-to-mods-1]

        In **Files**, upload **Fabric API + your mods** to the `mods/` folder.
      </Step>

      <Step>
        Start the server [#start-the-server-1]
      </Step>
    </Steps>

    > **Note:** Fabric mods are NOT compatible with Forge and vice versa. Check the mod page for the supported loader.
  </Tab>
</Tabs>

Client-Side vs Server-Side [#client-side-vs-server-side]

Not every mod needs to be on both. Check the mod's description to know:

| Type                 | Server Install | Client Install | Examples                                          |
| -------------------- | :------------: | :------------: | ------------------------------------------------- |
| **Server-side only** |        ✅       |        ❌       | Performance mods, server utilities, anti-cheat    |
| **Client-side only** |        ❌       |        ✅       | Shaders, minimaps, UI mods                        |
| **Both required**    |        ✅       |        ✅       | Most content mods (new blocks, items, dimensions) |

If a mod adds gameplay content, it's almost always **both required**.

Remove a Mod [#remove-a-mod]

<Steps>
  <Step>
    Stop the server [#stop-the-server-2]
  </Step>

  <Step>
    Delete the .jar [#delete-the-jar]

    In **Files**, navigate to `mods/` and delete the `.jar`.
  </Step>

  <Step>
    Start the server [#start-the-server-2]
  </Step>
</Steps>

> **Warning:** Removing mods that added new blocks/items can corrupt worlds containing those items. Players may see "missing blocks" replaced with the orange-and-black missing texture. **Always back up first** via **Backups** in the panel.

Common Issues [#common-issues]

| Problem                       | Fix                                                                                               |
| ----------------------------- | ------------------------------------------------------------------------------------------------- |
| **Mods not loading**          | Check that the `.jar` is in `mods/` (not a subfolder) and matches your loader (Forge ≠ Fabric)    |
| **"Mod requires Fabric API"** | Install Fabric API for the same Minecraft version                                                 |
| **Server crashes on startup** | Check **Console** for the stack trace. Remove the offending mod                                   |
| **Wrong Minecraft version**   | Mod must match your server version exactly. 1.20.1 mods won't work on 1.21                        |
| **Wrong Java version**        | Modern mods require Java 17 or 21. See [Java Version](/docs/minecraft/java-version)               |
| **Players can't connect**     | Client-required mods aren't installed on the player's side. Tell players to install matching mods |

Performance with Mods [#performance-with-mods]

Modded servers use significantly more RAM and CPU than vanilla. Recommendations:

| Mod Count       | RAM     |
| --------------- | ------- |
| 1–20            | 4–6 GB  |
| 20–50           | 6–8 GB  |
| 50–100          | 8–12 GB |
| 100+ (modpacks) | 12 GB+  |

See [Forge Optimize](/docs/minecraft/forge-optimize), [NeoForge Optimize](/docs/minecraft/neoforge-optimize), or [Fabric Optimize](/docs/minecraft/fabric-optimize) for tuning.

Related Guides [#related-guides]

* [Install a Modpack](/docs/minecraft/modpack-setup)
* [Java Version](/docs/minecraft/java-version)
* [Switch Server Version](/docs/minecraft/switch-version)
* [Forge Performance Guide](/docs/minecraft/forge-optimize)
* [Fabric Performance Guide](/docs/minecraft/fabric-optimize)