Skip to content
setup.md

Startup Scripts

Basics

This is how your most bare-bones startup script looks like.

Terminal window
...


java -Xmx<change-me>G -Xms<match-me-to-Xmx-value>G -jar <server-jar-name>.jar nogui


...

-Xmx sets the maximum amount of memory the Java Virtual Machine is allowed to reserve. Don’t set this over the amount of memory you have on your machine/given to you by the hosting provider.

-Xms sets the minimum amount of memory the JVM is allowed to reserve. It should always be below or equal to the -Xmx value.

The JVM only uses memory in its heap space - an area of memory that is reserved for the Java application (in our case, the server) - and the flags -Xms and -Xmx determine the possible bounds of this area. The heap size may be dynamically changed depending on how much memory the application actually needs, but it will always stay within those bounds.

For example, -Xmx3G -Xms1G would set the maximum heap size to 3 gigabytes and the minimum to 1 gigabyte. You can also use the letters M and K - megabytes and kilobytes (though the latter is not usually used) to set the value more precisely, e.t -Xmx512M.

Setting them both to be the same usually improves performance as no calculations need to be done regarding the heap size, but this may take away memory from other programs on your host machine (if any) in case the server does not always need to allocate the full -Xmx.

You should set your RAM allocation according to your average server load - allocating more memory than your server needs is likely to cause GC lag spikes. For example, if you are a starting out server with 0-2 players most of the time, you’ll be fine with 2 GB, but if you have 5-10 players online at once, you’ll need 4-5 GB.

nogui hides the Minecraft server GUI panel, only leaving the console visible. Remove the flag if you choose to use the panel. It has basic features like a player list, performance metrics and console output.

-jar <server-jar-name>.jar points to the server .jar - see Server Software.

Java flags

Java flags are used to improve server performance and client stuttering by tuning Java’s Garbage Collection and adding other optimizations.

JVM flags go before the -jar flag.

Aikar flags

Aikar’s flags, while very well optimized for older Java versions, have not been updated since its creation and are severely out of date for modern Java versions. If you are running a 1.17+ Minecraft Java server (and use java 16+), it is recommended to use more up-to-date flags.

Hilltty flags

These flags are a more up to date version of Aikar’s flags designed for modern versions of Java (16 and 17) which should perform better. You can check the startup scripts here.

Advanced JVM flags and optimizations

The JVM can be further tweaked to optimize server and client stutters relating to Java. See Minecraft Performance Flags, a up-to-date guide for Java flags, Garbage Collectors, Java runtimes (GraalVM), and other performance tips such as Large Pages and optimized Linux Distributions.

Minecraft server flags

Minecraft also has quite a few startup options that directly affects the server in some way. Those go after -jar in the startup script. The following information is from the wiki.

Minecraft options

  • --bonusChest

If a bonus chest should be generated, when the world is first generated.

  • --demo

If the server is in demo mode. (Shows the players a demo pop-up, and players cannot break or place blocks or eat if the demo time has expired) Equivalent to playing minecraft without a account, you have about 5 in-game days before your trial ends.

  • --eraseCache

Erases the lighting caches, etc. Same option as when optimizing single player worlds.

  • --forceUpgrade

Forces upgrade on all the chunks, such that the data version of all chunks matches the current server version (same as with sp worlds). This option significantly increases the time needed to start the server.

  • --initSettings

Loads the settings from ‘server.properties’ and ‘eula.txt’, then quits.

  • --jfrprofile

Initializes the Java Flight Recorder on the server. Only available on 1.18+.

  • --port <Integer>

Which port to listen on, overrides the server.properties value. (default: -1, read from server.properties)

See Server.properties for restrictions on this value.

  • --safeMode

Loads level with vanilla datapack only.

  • --serverId <String>

Gives an ID to the server. (??) Seemingly no effect ??

  • --singleplayer

Runs the server in offline mode.

  • --universe <String>

The folder in which to look for world folders. (default: .)

  • --world <String>

The name of the world folder in which the level.dat resides.