# nix-minecraft: running Minecraft servers as Nix packages

> nix-minecraft turns Minecraft server software into Nix derivations and a NixOS module, so vanilla, mod loader and proxy servers can be declared, pinned and built reproducibly. It is built for people who already run Nix and want server management to look like configuration rather than downloads.

**Infinidoge/nix-minecraft** — An attempt to better support Minecraft-related content for the Nix ecosystem

- Repository: https://github.com/Infinidoge/nix-minecraft
- Stars: 631 · Forks: 93
- Language: Nix
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/infinidoge-nix-minecraft

## What nix-minecraft packages and who it is for

The project describes itself as an attempt to better package and support Minecraft as part of the Nix ecosystem, and the focus is server side rather than the client. The README lists what is currently packaged: all versions of Vanilla servers, supported versions of Fabric, Legacy Fabric, Quilt, Paper, Purpur and NeoForge, the Velocity proxy, and a small set of tools called `nix-modrinth-prefetch`, `fetchPackwizModpack` and `fetchModrinthModpack`.

That list defines the audience more precisely than the phrase Nix ecosystem does. A Minecraft client needs a launcher, an account login and a shader stack, none of which this project supplies. A Minecraft server needs a jar, a working directory, a service unit and a set of configuration files, and every one of those can be expressed as a Nix derivation or a NixOS option. So the people who benefit are the ones deploying servers from a NixOS host, or from any machine that already builds with Nix, and who want the server jar to be pinned to an exact version instead of downloaded at boot.

The license is MIT and the default branch is master. The repository has no GitHub releases, so version history lives in the changelog file rather than in tagged release artifacts. The last push was on 2026-10-20, which puts the work in recent territory, though the README itself points to an example video and an examples directory rather than to release notes, so the documentation lags the code in places.

## The flake input and the two pieces it gives you

Everything is delivered as a Nix flake, which is the only distribution mechanism the project offers. The input declaration in your own flake is short, and the same input is then consumed twice: once as a NixOS module for the service definitions, and once as an overlay that injects the packaged servers into your package set.

```nix
{
  inputs = {
    nix-minecraft.url = "github:Infinidoge/nix-minecraft";
  };
}
```

In a system configuration you import the module and add the overlay. The module name is `minecraft-servers`, and the overlay attribute is `overlay`.

```nix
{ inputs, ... }: # Make sure the flake inputs are in your system's config
{
  imports = [ inputs.nix-minecraft.nixosModules.minecraft-servers ];
  nixpkgs.overlays = [ inputs.nix-minecraft.overlay ];
}
```

The README mentions that `flake-compat` is included for people who are not using flakes, but it adds that this path is not actively tested because the author uses flakes. That is a small warning sign for a project that many newcomers will meet before they are comfortable with flakes in general.

The repository also ships `default.nix`, `overlay.nix`, a `lib/` directory, a `modules/` directory and a `pkgs/` directory with one subdirectory per server type, plus `examples/single-server/` and `examples/single-server-with-mods/` for people who want a working starting point rather than a blank page.

## Versioned attributes, the latest shortcut, and override

Each server family is exposed as an attrset of derivations keyed by version. The naming convention replaces every period and space with `_`, so `1.18.2` becomes `1_18_2` and snapshot versions such as `22w16b` keep their original shape.

```nix
vanillaServers.vanilla-1_18_2
vanillaServers.vanilla-22w16b
vanillaServers.vanilla-22w13oneblockatatime
```

A convenience attribute `vanillaServers.vanilla` points at the latest major version, so a config that only wants the newest server never has to edit a version string.

The Fabric family follows the same pattern, with an extra knob. The Fabric version is always the latest released one, and if you need a specific loader you override the derivation and set `loaderVersion`.

```nix
fabricServers.fabric-1_18_2
fabricServers.fabric-22w16b
fabricServers.fabric-1_18_2.override { loaderVersion = "0.14.20"; } # Specific fabric loader version
```

The README states that the Minecraft version must be at least `1.14` for Fabric and that the loader version must be at least `0.10.7`. Quilt and Legacy Fabric mirror the Fabric layout, with one structural difference: because Legacy Fabric has no defined newest version to target, that family has no `legacy-fabric` convenience attribute. The NeoForge family is keyed by both game version and NeoForge version, and its lowest supported version is `20.4.240`.

```nix
neoforgeServers.neoforge-1_21_1
neoforgeServers.neoforge-1_21_1-21_1_193
```

## The minecraftServers union and the offline vanilla jar

The `minecraftServers` attribute is the union of the vanilla, Fabric, Quilt, Legacy Fabric, Paper, Purpur and NeoForge families, and it is the one most configs reach for. When the overlay is enabled it replaces the Nixpkgs attribute of the same name, so a config that referenced the Nixpkgs version keeps working but resolves to a different derivation.

Paper and Purpur carry an operational detail that the rest of the project does not. If you intend to run them without internet access, you have to link the vanilla jar into `cache/mojang_{version}.jar`. The jar is available through the package's `vanillaJar` attribute, which means the offline path is a link, not a manual download, but it is a step that does not exist for the other families.

The Velocity family is also laid out differently. Its versions do not include or depend on specific Minecraft versions at all, so `velocityServers.velocity` resolves to the latest proxy release on its own terms.

The practical consequence is that two behaviours under one name hide behind one attribute. If a config reaches for `minecraftServers` without knowing which family a version string belongs to, a Paper build can be selected where a Vanilla build was intended, and the difference shows up at runtime rather than at evaluation time. Version strings are the only guard here, and Nix will not warn you that a Paper derivation needs a linked vanilla jar that you forgot to provide.

## Modpacks: fetchPackwizModpack and the read-only mods problem

The `fetchPackwizModpack` function packages a packwiz modpack so it can be run on your own server. The call takes a manifest URL and a hash.

```nix
  let
    modpack = pkgs.fetchPackwizModpack {
      url = "https://github.com/Misterio77/Modpack/raw/0.2.9/pack.toml";
      packHash = "sha256-L5RiSktqtSQBDecVfGj1iDaXV+E90zrNEcf4jtsg+wk=";
    };
```

The README warns about a failure that is easy to hit: the manifest URL must be stable, a git tag or a commit, because a changing URL produces a different hash and the build breaks until you change the hash yourself. That is a deliberate trade of convenience for reproducibility.

A second warning is more interesting. Symlinking the modpack's `mods` directory into the server's `mods` directory means that directory is read-only and is replaced wholesale, so adding a single extra mod by hand fails, and adding config files one at a time is described as boring. The project answers this with a `collectFilesAt` function. The README excerpt ends right where that function is introduced, so its exact signature is not spelled out there, and the README does not document the arguments it takes.

## A 30 day deprecation window and evaluation warnings

Maintenance policy is stated plainly. When something is deprecated, an announcement is added to the changelog file, and the corresponding parts in Nix are marked with an evaluation warning. Deprecated code is subject to removal after one month.

This is a short window, and it is worth reading twice. One month is long enough to notice a `nix build` that now prints a warning, and short enough that a deprecated attribute can disappear while you were on holiday. The evaluation warning is the important part, because it surfaces the problem at build time on the machine that will actually fail, rather than in a release note you have to go looking for.

The repository also has a `CHANGELOG.md`, a `TODO.md` and a `CONTRIBUTING.md` at the top level. The README points at the changelog for release information and at the TODO file for the roadmap, so planned work is visible in the repository, but the README itself gives no version numbers and the project has no GitHub releases to check.

The last push was on 2026-10-20, so the code is being changed. Whether a given attribute survives the deprecation policy is a question you can only answer by reading the changelog, which is why that file is the first thing to check before pinning anything in a long lived deployment.

## Where nix-minecraft is the wrong tool

The obvious wrong case is a single vanilla world for a handful of friends. The overhead of a NixOS module, an overlay and a flake lock is large relative to the problem, and the server jar itself is free to download.

The second wrong case is any deployment without Nix. The project ships as a flake and nothing else, and even the `flake-compat` fallback is not actively tested. There is no standalone binary to install, no Homebrew formula and no container image mentioned in the README.

The third wrong case is a client-side setup. The README is explicit that the effort focuses on the server side, so a launcher, an account flow and shader configuration are all out of scope.

A fourth case deserves its own note. The alternative approach to server distribution is to run the official or community jar under a plain service manager and download the mod or plugin set at deployment time with a separate downloader. The difference in approach is one of build provenance: this project makes the server a derivation with a hash, so the artifact is reproducible and the build is declarative, while the download approach makes the jar an opaque input that changes whenever the upstream publisher publishes. The cost of the declarative route is the learning curve of Nix itself, plus the fact that the versioned attributes and the deprecation window become constraints you have to track.

Readiness for real use also depends on network access. Paper and Purpur in an offline network need a linked vanilla jar, and a modpack manifest needs a stable URL and a matching hash, so a locked down environment needs planning rather than a one line install.

## Conclusion

nix-minecraft fits operators who already declare infrastructure in Nix and want pinned server builds plus declarative service management. It is a poor fit for a single vanilla world on a Raspberry Pi, for players who need a launcher, or for anyone unwilling to learn NixOS module syntax. Before adopting it, check the changelog for deprecation notices, confirm the exact Minecraft and loader version you need exists in the versioned attributes, and decide how you will supply the vanilla jar for Paper and Purpur if the server has no outbound network access.

## FAQ

### How do I add nix-minecraft to a NixOS configuration?

Add the flake input as `github:Infinidoge/nix-minecraft`, then import `inputs.nix-minecraft.nixosModules.minecraft-servers` and add `inputs.nix-minecraft.overlay` to `nixpkgs.overlays`.

### Which Minecraft server versions and mod loaders does nix-minecraft support?

All versions of Vanilla servers, plus supported versions of Fabric, Legacy Fabric, Quilt, Paper, Purpur and NeoForge, and the Velocity proxy. Fabric requires a Minecraft version of at least 1.14, the lowest supported NeoForge version is 20.4.240, and Legacy Fabric has no `legacy-fabric` attribute for the latest version.

### How do I run a Paper server without internet access?

You have to link the vanilla jar to `cache/mojang_{version}.jar`. The jar to use is exposed by the package's `vanillaJar` attribute.

### Can I pin a specific Fabric loader version in nix-minecraft?

Yes, by overriding the derivation and setting `loaderVersion`, for example `fabricServers.fabric-1_18_2.override { loaderVersion = "0.14.20"; }`. The loader version must be at least 0.10.7.

### Why does my modpack build fail after the packwiz manifest changes?

The manifest URL has to be stable, such as a git tag or a commit, because a changing URL makes the derivation produce a different hash, which breaks the build until you update the hash yourself.

### How long does nix-minecraft keep deprecated packages?

Deprecation is announced in the changelog file and the affected Nix parts are marked with an evaluation warning, and deprecated code is subject to removal after one month.

## Sources

- [Infinidoge/nix-minecraft on GitHub](https://github.com/Infinidoge/nix-minecraft)
- [Issues](https://github.com/Infinidoge/nix-minecraft/issues)
- [License: MIT](https://github.com/Infinidoge/nix-minecraft/blob/master/LICENSE)
- [README](https://github.com/Infinidoge/nix-minecraft/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/infinidoge-nix-minecraft