Minestom: a Minecraft server library with no vanilla features built in

What Minestom actually is, and who it is for

Minestom is an open-source library that lets developers create their own Minecraft server software without any code from Mojang. That sentence from the README is the whole product in one line. It is not a server jar you download and run. It is a Java dependency you add to your build, compile against, and ship as your own program.

The README is explicit about the audience: "This is a developer API not meant to be used by end-users." If you drop Minestom where Bukkit, Forge or Sponge would go, nothing works, because none of those APIs are implemented. The project's own framing is that it suits servers which benefit little from vanilla features, and it names creative and kitpvp as examples. The stated rule of thumb is blunt: use Minestom when implementing the missing vanilla features you want takes less time than stripping out the vanilla features that slow you down. That is a real decision, not a slogan, and for a survival server with redstone, mob AI and world persistence the answer is usually no.

So the target reader is a Java developer with a game concept that does not need vanilla systems, who wants control over the network and world layer rather than a plugin API.

Instances, blocks and entities: the mechanism you build on

The central concept is the instance, described in the README as a collection of blocks and entities. Worlds, in the project's view, work for survival with friends but become unmanageable at scale, forcing everything into files and carrying data you do not need. Instances are lightweight by comparison: chunks can live only in memory, be copied, and be sent to another player, with custom serialization available. Creating instances on the fly is presented as a first-class operation.

The threading model is the second half of the design. Rather than a single thread, or one thread per world, Minestom uses a fixed pool of threads to manage all chunks independently from instances. The README lists multi-threaded operation as an advantage and, in the same section, lists multi-threaded environments needing extra consideration as a disadvantage. Both are true. You get more CPU in play, and you take on the responsibility of reasoning about concurrent access to your own game state.

Blocks follow the same philosophy. Minestom does not know what a chest is. Every block that is more than visual needs a specialized handler you register; after that it can be placed anywhere. Blocks are visually present by default, they simply have no interaction until you give them one. Entities are similar: the passive and aggressive categories do not exist, and the README's example of the freedom this gives is a flying chicken that rushes players. With NMS, the README argues, that kind of change is a mess because of obfuscation.

Installing Minestom as a Gradle dependency

There is no installer, no server directory and no start script. The README states that Minestom must be loaded the way any Java library is loaded: add it as a dependency, add your code, compile it yourself. It is published on Maven Central. The README gives the Gradle/Kotlin form, and the version placeholder is written as `<latest release>` in the source, so you replace it with the release you want.

repositories {
    mavenCentral()
}

dependencies {
    implementation("net.minestom:minestom:<latest release>")

    // If you want to use the integration testing library.
    testImplementation("net.minestom:testing:<latest release>")
}

The second dependency, `net.minestom:testing`, is the integration testing library, and it is optional. If you want unreleased features, the README describes snapshot publishing: pull request branches carrying the "Publish Pull Request" tag go to the Maven Central snapshot repository, and the version is `<branch>-SNAPSHOT`, with `master-SNAPSHOT` also published.

repositories {
    maven(url = "https://central.sonatype.com/repository/maven-snapshots/") {
        content { // This filtering is optional, but recommended
            includeModule("net.minestom", "minestom")
            includeModule("net.minestom", "testing")
        }
    }
    mavenCentral()
}

One detail worth reading twice: a `<branch>-SNAPSHOT` version resolves to the newest snapshot every time, so your build can change without your build file changing, and Gradle caches it for 24 hours by default. The README documents how to pin an exact build using the `snapshot.timestamp` and `snapshot.buildNumber` parts of `maven-metadata.xml`, or by expanding the snapshot jar under External Libraries in IntelliJ. For anything you intend to reproduce, pin it.

For a first real use, the README points to the `demo` directory in the repository, and to the wiki at wiki.minestom.net and the javadocs. That is where a runnable starting point lives; the README itself does not inline a main class. The repository layout also shows `jmh-benchmarks/` and `jcstress-tests/`, which tells you the project benchmarks itself and tests concurrency separately.

The limitations the README admits, and the ones it implies

The disadvantages list is unusually honest. Minestom does not work with Bukkit, Forge or Sponge plugins or mods. It does not work with older clients, though the README notes a proxy with ViaBackwards is possible. It is described as bad for those who want a vanilla experience, and slower to get to something playable. Those four items are the adoption cost, stated plainly.

The subtler failure mode is the empty default. A Minestom server with no code does nothing useful, because nothing is included by default. Every interaction you expect from Minecraft has to be written: block handlers, entity behaviour, inventory logic, persistence choices. The instance model makes chunks in-memory by default, which is fast and also means persistence is your problem, since the README frames file-based saving as the thing instances avoid. The README does not document a rollback or recovery story for that.

Concurrency is the third boundary. A fixed thread pool over chunks is a performance choice with a correctness bill attached, and the README itself flags multi-threaded environments as needing extra consideration. If your team has not written concurrent Java before, this is the part where bugs will live.

Finally, the project is a library, so there is no support contract, no admin commands, and no plugin ecosystem to borrow from. You are the vendor of your own server.

Minestom compared with Paper and Spigot

The comparison people search for is Minestom versus Paper or Spigot, and the difference is architectural rather than a matter of tuning. Paper and Spigot are forks of the vanilla server: you run their jar, and you extend behaviour through plugins against their API. Minestom is the opposite starting point. There is no jar to run, no plugin loader, and no vanilla feature set. You compile a program that embeds the library.

That inverts where the work goes. On Paper, you inherit world formats, mob AI, redstone, commands and persistence, and you fight the parts you do not want. On Minestom, you inherit nothing and add what you need. The README's own framing captures the trade: it makes sense when implementing the missing vanilla features takes less time than removing the vanilla features that slow you down.

The threading story differs too. Paper is built around the vanilla server's structure; Minestom replaces worlds with instances and manages chunks with a fixed thread pool independent of instances. The practical consequence is that a minigame server with many small, independent arenas maps naturally onto instances, while a persistent survival world with heavy vanilla simulation does not map onto Minestom at all. If you need Spigot plugins, Minestom is not a faster Spigot, it is a different product.

Maintenance, releases and the Apache-2.0 licence

The repository is not archived and the last push was on 2026-09-22, two days before this writing, so it is under current development. Releases follow a dated scheme: 2026.09.12-26.2, 2026.08.28-26.2 and 2026.08.16-26.2, roughly every two weeks. The version suffix tracks a Minecraft protocol line, and the README's snapshot pinning example mentions a `1_21_6-SNAPSHOT` branch, so branches correspond to protocol versions. The practical upgrade cost is that you track a moving library against a moving client protocol, and the README's warning about snapshot resolution means an unpinned dependency can shift under you.

The licence is Apache-2.0, which permits commercial and closed-source use with the usual obligations around notices and attribution. That matters here because you are shipping a compiled product that embeds the library, not running someone else's jar. This is a description of the licence identifier and not legal advice; read the LICENSE file in the repository for the terms that apply to you.

The codebase carries `jcstress-tests/` and `jmh-benchmarks/` alongside `src/`, which indicates the project maintains its own concurrency tests and benchmarks. That is a signal about engineering practice, not a guarantee about your workload.

Editorial conclusion

Adopt Minestom if you are a Java developer building a minigame, creative or kitpvp server and you accept writing the missing vanilla behaviour yourself. Do not adopt it if you need Bukkit, Forge or Sponge plugins, older clients, or a survival experience that works out of the box. Before committing, read the demo module and the wiki, then decide whether the instance model fits your chunk and entity workload.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Minestom/Minestom on GitHub
3. Project website
4. README
5. Releases