NeoForge server setup: install to first boot

To set up a NeoForge server, download the NeoForge installer for your Minecraft version, run it with --installServer in an empty folder, put your memory settings in user_jvm_args.txt, accept the EULA, and start it with run.sh (or run.bat on Windows) rather than java -jar. Mods go in mods/, their settings appear in config/ and in the world's serverconfig/ after the first boot, and every player needs the same mods at the same versions. The part that trips people up is that a modern NeoForge server has no single jar to run - the start script is the launcher - which matters a great deal on hosting panels built around java -jar.

NeoForge, Forge, and which version you need#

NeoForge is a fork of Forge that split from it in 2023. For Minecraft 1.20.1 it shipped builds that were nearly identical to Forge, under Forge's old version numbers. From 1.20.2 onwards it is a separate loader with its own versioning, and most new Forge-lineage modpacks target NeoForge rather than Forge.

The version number tells you the Minecraft version it is built for:

The pattern from 1.20.2 is that NeoForge's first two numbers are Minecraft's second and third, and the last number is the build. The NeoForge website lists the current builds for each version; use the one your modpack names, or the latest stable build for that Minecraft version if you are building your own.

Two compatibility facts save a lot of confusion:

• Forge mods do not load on NeoForge from 1.20.2 onwards without the author rebuilding them. On 1.20.1 most Forge mods work on NeoForge, which is why many 1.20.1 packs still run Forge.
• From 1.20.5, NeoForge mods describe themselves in `META-INF/neoforge.mods.toml` instead of Forge's mods.toml. A Forge mod dropped into a NeoForge 1.21 server is not recognised as a mod at all, which can look like the mod simply being ignored.

The Java column is not negotiable. A 1.21 NeoForge server on Java 17 fails immediately with an UnsupportedClassVersionError; a 1.20.1 pack on a much newer Java can fail in stranger ways. JVM flags and Java versions has the full table and the heap sizing that goes with it.

Running the installer#

The installer is a small jar that downloads the vanilla server, the NeoForge libraries and the mappings, and writes the launch files. It needs Java and an internet connection, and it should be run in an empty folder.

$ mkdir neoforge-server && cd neoforge-server$ curl -O https://maven.neoforged.net/releases/net/neoforged/neoforge/21.1.77/neoforge-21.1.77-installer.jar$ java -jar neoforge-21.1.77-installer.jar --installServer

The version in those lines is an example. When it finishes, the folder contains:

You can delete the installer jar and its log once the install has succeeded. Do not delete or rearrange libraries/ - the start script refers to a file inside it by path.

run.sh and user_jvm_args.txt#

Open run.sh and you will see something close to this:

#!/usr/bin/env sh# Add custom JVM arguments to user_jvm_args.txt# Add custom program arguments (such as nogui) before "$@"java @user_jvm_args.txt @libraries/net/neoforged/neoforge/21.1.77/unix_args.txt "$@"

The @file syntax tells Java to read arguments from a file. user_jvm_args.txt is yours; unix_args.txt (or win_args.txt) inside libraries/ belongs to NeoForge and holds the module path, the main class and the rest of what the loader needs. Never edit the second one - it is regenerated when you update NeoForge, and getting it wrong produces errors about missing modules that are very hard to read.

Memory and flags go in user_jvm_args.txt, one or more per line. The installer writes it full of comments and with the memory line commented out:

# Xmx and Xms set the maximum and minimum RAM usage.-Xms6G-Xmx6G-XX:+UseG1GC-XX:+ParallelRefProcEnabled-XX:MaxGCPauseMillis=200

Size -Xmx below the memory limit of the machine or container, not equal to it. Java uses memory outside the heap - metaspace, thread stacks, native buffers - and modded servers use more of that than vanilla because of the sheer number of classes. On a container with an 8 GB limit, a heap of about 6.5 GB is a reasonable ceiling. If the heap fills the container, the process is killed from outside with no crash report at all.

Add nogui as a program argument so the server does not try to open its status window, either by passing it to the script (./run.sh nogui) or by adding it before "$@" in the script itself.

The first boot#

The first start is the slowest a NeoForge server will ever be, and it does three things you need to know about.

1. It stops at the EULA. The server writes eula.txt with eula=false and exits. Change it to eula=true and start again. That line is your agreement to Mojang's EULA, which is also why no installer can set it for you without asking.
2. It generates configs. Every mod writes its default settings. Common and startup settings go in config/; settings the server owns for a particular world go in the world's own folder, under world/serverconfig/, and are created when the world is.
3. It generates the world. A modded world with worldgen mods is much slower to create than a vanilla one. Spawn chunk generation on a large pack can take minutes.

[main/INFO] [net.neoforged.fml.loading.moddiscovery...]: Found 142 mods[Server thread/INFO] [minecraft/MinecraftServer]: Preparing level "world"[Server thread/INFO] [minecraft/MinecraftServer]: Done (94.512s)! For help, type "help"

Done is the line that matters. Until it appears, the server is still loading, however long it takes.

Two files decide where per-world configs come from:

• `defaultconfigs/` in the server root holds templates. When a new world is created, any server config found here is copied into the world's serverconfig/ instead of the mod's built-in default. Modpacks use this to ship their tuned settings.
• `world/serverconfig/` holds the live copies for that world. Edit these for an existing world, with the server stopped. Editing defaultconfigs/ does nothing to a world that already exists.

That split is the source of the classic "I changed the config and nothing happened" report: the file edited was the template, and the world was already using its own copy.

Mods, and what has to match on the client#

Mods go in mods/ as jar files. NeoForge reads them all at startup, checks the dependencies each declares, and refuses to start if one is missing or out of range, naming the mod and the version it wanted. That message is usually clear; read it before searching for it.

The other rule is about players. Any mod that adds blocks, items, entities, dimensions or recipes must be installed on the client too, at the same version. Players should get the pack through a launcher that installs exactly what the server has - CurseForge, Modrinth, Prism Launcher or a pack the server provides. Modpack servers from CurseForge and Modrinth covers turning a published pack into a server.

The mods that must not be on the server are client-only: renderers, shader loaders, minimaps that only draw, HUD and menu mods. On NeoForge a client-only mod on a server tends to crash the start with a message like this:

java.lang.RuntimeException: Attempted to load class net/minecraft/client/...for invalid dist DEDICATED_SERVER

The stack trace below that line names the mod responsible. Remove it from the server's mods/ folder, not from the players' packs. Running a modded server without the crashes has a longer guide to reading these reports.

Starting it on a hosting panel#

On your own Linux machine you run ./run.sh nogui inside screen, tmux or a systemd service and you are done. Hosting panels are different. Most run the server with a start command that expects one jar - something like java -Xmx... -jar server.jar - and a modern NeoForge server does not have that jar.

There are two clean ways through:

• A start command that calls the argument files. If the start command can be set to java @user_jvm_args.txt @libraries/net/neoforged/neoforge/<version>/unix_args.txt nogui, the server starts exactly as run.sh would start it. Remember to change the version in that path whenever you update NeoForge.
• A server starter jar. Recent NeoForge installers can drop in a small starter jar for hosts that can only run java -jar; it reads the same argument files and launches the server for you. Run the installer with --help to see whether your version offers it and what the option is called.

Whichever you use, set the memory in exactly one place. If the panel passes its own -Xmx and user_jvm_args.txt contains another, Java takes whichever comes last on the command line, and you will spend an evening wondering why the heap is the wrong size.

On RE:NODE the Minecraft line is installed with Paper and the matching Java version, so NeoForge is something you set up yourself: upload the installed folder as an archive through the file manager (it unpacks archives in place) or over SFTP, check the Java version and the jar on the Startup tab, and start it. There is no whitelist of allowed mods and no one-click modpack installer. The upside of doing it yourself is that you know exactly which NeoForge build and which mods are on the server.

Settings worth changing on a modded server#

A few vanilla settings in server.properties matter more on NeoForge than on Paper:

view-distance=8simulation-distance=6max-tick-time=60000allow-flight=true

The reasoning behind each:

• `view-distance` and `simulation-distance` multiply the number of loaded chunks, and modded chunks are heavier. Start lower than you would on vanilla and raise them only if MSPT has room.
• `max-tick-time` is the watchdog: if one tick takes longer than this many milliseconds, the server deliberately crashes itself. The default is 60000. Large packs sometimes trip it during world generation or a big save. -1 disables the watchdog entirely, which hides real hangs; raising it is better than turning it off.
• `allow-flight=true` is common on modded servers, because jetpacks, flight rings and creative-flight items look exactly like flying to the vanilla anti-fly check, which kicks the player for it.

Pre-generate the world before people play on it. Worldgen mods make chunk generation several times more expensive, and generating terrain during play is where most "random" lag spikes come from on a modded server. Chunky runs on NeoForge; world borders and pre-generation has the procedure.

Updating NeoForge and keeping it running#

Updating NeoForge within the same Minecraft version means running the newer installer in the same folder. It writes new libraries and updates the scripts; your mods/, config/, world and user_jvm_args.txt are left alone. If your panel start command points at the version path inside libraries/, update that path too.

The safe order:

1. Stop the server and take a backup of the world, mods/, config/ and defaultconfigs/ together. A world restored next to the wrong mod versions is not a restore.
2. Write down the versions you are on: Minecraft, NeoForge, the pack and Java.
3. Install the new NeoForge build, start with nobody online, and read the log from the top.
4. Join and check the areas where people built before announcing it.

Changing the Minecraft version is a different job: every mod has to be replaced by its build for the new version, and many will not exist yet. Treat it as a new server that happens to inherit a world, and read Minecraft version upgrades first.

Backup slots are included on every RE:NODE Minecraft plan, stored off the machine they protect, and one can be locked against rotation while you test an update. Restoring is one button, which is the right amount of effort for undoing a modded update that went wrong.

FAQ#

Why is there no server jar after installing NeoForge?

Since the Forge-lineage loaders moved to the module system, the installer writes a libraries/ tree and launch scripts instead of one runnable jar. The scripts pass two argument files to Java, and that is what starts the server. Use the scripts, an equivalent start command, or a server starter jar.

Can I put Forge mods on a NeoForge server?

On 1.20.1, mostly yes, because NeoForge for that version is very close to Forge. From 1.20.2 onwards, no - the two loaders have diverged and a mod needs a NeoForge build. From 1.20.5 a Forge mod is not even recognised as a mod by NeoForge.

How much memory does a NeoForge server need?

A light pack with 50 to 100 mods is usually comfortable with 4 to 6 GB of heap for a small group. Large kitchen-sink packs with several hundred mods often need 8 GB or more. How much RAM a Minecraft server needs has the detail; always leave headroom between the heap and the container limit.

Can vanilla players join a NeoForge server?

Only if every mod on the server is server-side and does not require anything on the client. As soon as a mod adds content, vanilla clients are refused. In practice, a NeoForge server is played with a matching modpack.

Where do I change a mod's settings for my world?

In world/serverconfig/ for settings the server owns, and in config/ for common ones, with the server stopped. Files in defaultconfigs/ only apply when a new world is created.