Minecraft Server

⤧︎

Disambiguation: Not to be confused with the Minecraft client.

🟆︎

Tip: This package is unfree, and will require extra steps to install. You can read more about allowing unfree software in the Nixpkgs Manual.

Minecraft Server is a server for the sandbox game Minecraft. Currently, only servers for the Java Edition of Minecraft are supported.

Setup

The minimum example to have a Minecraft server running on localhost at the default port of 25565. By setting the eula option to true, you are agreeing to the Minecraft EULA.

❄︎ /etc/nixos/configuration.nix

services.minecraft-server.enable = true;
services.minecraft-server.eula = true;

Configuration

This example is a more thorough declarative configuration that sets a few options including opening the firewall, restricting the server to only whitelisted users and setting the port to 43000.

❄︎ /etc/nixos/configuration.nix

services.minecraft-server = {
  enable = true;
  eula = true;
  openFirewall = true; # Opens the port the server is running on (by default 25565 but in this case 43000)
  declarative = true;
  whitelist = {
    # This is a mapping of Minecraft usernames to to the players' UUIDs
    username1 = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
    username2 = "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy";
  };
  serverProperties = {
    server-port = 43000;
    difficulty = 3;
    gamemode = 1;
    max-players = 5;
    motd = "NixOS Minecraft server!";
    white-list = true;
    allow-cheats = true;
  };
  jvmOpts = "-Xms2048M -Xmx2048M"; 
};

You might want to view the list of all available server properties for the vanilla server.

See #See also for recommended JVM flags for the jvmOpts option. These primarily depend on your Java version.

Modded servers

Minecraft-server provides both support for vanilla and Papermc servers. If you would like to install other mod-loaders such as Fabric and Quilt, you would have to take a slightly different approach;

Mod-loaders on Nixpkgs

Mod-loader	Is available on Nixpkgs?
Vanilla	Yes
Fabric	No
Quilt	No
Paper	Yes
Purpur	Yes
NeoForge	No
Velocity	No

Using flakes

Nix-minecraft is a Nix flakes based attempt at better supporting modded servers and has support for managing multiple servers on one system.

Check out the install guide for installing Nix-minecraft.

Here is the above example configuration.nix but with fabric 26.2, and the server called example

❄︎ configuration.nix

services.minecraft-servers = {
  enable = true;
  eula = true;
    servers.example = {
      openFirewall = true; # Opens the port the server is running on (by default 25565 but in this case 43000)
      
      # Specifies what package the server should run on
      # This example uses the current latest version of Fabric
      # The override is here due to a little quirk with nix-minecraft (more detail  below this code block)
      package = pkgs.fabricServers.fabric-26_2.override { jre_headless = pkgs.openjdk25_headless; };

      whitelist = {
        # This is a mapping of Minecraft usernames to to the players' UUIDs
        username1 = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
        username2 = "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy";
      };
      serverProperties = {
        server-port = 43000;
        difficulty = 3;
        gamemode = 1;
        max-players = 5;
        motd = "NixOS Minecraft server!";
        white-list = true;
        allow-cheats = true;
      };
      jvmOpts = "-Xms2048M -Xmx2048M"; 
    };
};

Package syntax

pkgs.<loader>Servers.<loader>-<version> # for a specific release. 

pkgs.<loader>-server # for the latest release
pkgs.<loader>Servers.<loader> # equivalent to above

^{<loader> refers to the mod loader, such as vanilla , fabric, quilt, paper, purpur, neoforge, and velocity. <version> refers to the version of minecraft, formatted as 26_1_2, 1_18_2, or 25w10a.}

Why the override?

Due to mojang changing the version formatting in versions ≥26.1. The packages (not in nixpkgs) use the wrong version of Java

# fabric 26.1 with the correct java version
pkgs.fabricServers.fabric-26_1.override { jre_headless = pkgs.openjdk25_headless }

Imperatively (server.jar)

Some mods like BTA!, are not supported by Nix-minecraft nor nixpkgs. If so then using the server.jar file might be a simpler approach.

^{Make sure to move the server.jar file inside a separate directory, or else it might spawn server files where you don't want them.}

Installation

Step 1. Install the appropriate version of Java .

pkgs.jdkX # replace the 'X' with the correct java version number here

Step 2. Run the provided server.jar with java (add any extra JVM args as you see fit)

java -Xmx4G -jar /path/to/server.jar -nogui

The -Xmx flag sets the max memory allocation (here 4GB). The -nogui flag disables the minecraft server gui

Tips and tricks

Accessing the Minecraft server console

The Minecraft server console allows you to view server logs and issue commands to the server interactively. The Minecraft server console is not directly accessible on NixOS—unlike on non-declarative systems, where running the server through a shell command provides the interactive console to the current terminal.

Accessing logs

Since the Minecraft server runs as a systemd service, you can access its stdout through the systemd journal:

journalctl -eu minecraft-server.service

The logs are also available in the logs subdirectory of the server's data directory, which is configured via services.minecraft-server.dataDir. The default value for this option is /var/lib/minecraft.

Issuing commands

There are two ways to issue commands to the Minecraft server:

1. Writing to the server’s stdin via its named pipe at /run/minecraft-server.stdin:

echo "say Removed Herobrine" > /run/minecraft-server.stdin

2. Using the server's provided RCON feature.

Example minimal configuration:

❄︎ /etc/nixos/configuration.nix

 services.minecraft-server.serverProperties = {
    enable-rcon = true;
    "rcon.password" = "your password";
 };

Use a different server

To use a specific server version, or another Minecraft server—such as PaperMC—change services.minecraft-server.package to a nix package that represents your desired server.

For example:

services.minecraft-server.package = pkgs.minecraftServers.vanilla-1-12;

or

services.minecraft-server.package = pkgs.papermc;

Prefer IPv4

To use IPv4 by default, add -Djava.net.preferIPv4Stack=true to jvmOpts.

See also

• nix-minecraft, a flake based attempt to better support Minecraft related content for the Nix ecosystem. It can be used for more complex server setups, including mods and plugins.
• https://exa.y2k.diy/garden/jvm-args for setting additional JVM flags in the jvmOpts option. Some server-related software—like the Velocity proxy—have their own recommended JVM flags list.
• https://mcuuid.net to get a player's UUID from their current username or vice versa.