PaperMC Folia: regionised multithreading for Minecraft servers

What Folia changes about the Minecraft tick loop

Paper runs one main thread that ticks every world, every chunk and every entity in order. Folia removes that thread. The README states that nearby loaded chunks are grouped into an independent region, each region gets its own tick loop at the regular 20TPS rate, and those loops run in parallel on a thread pool. The practical consequence is that a server with many spread-out players produces many spread-out regions, and those regions tick at the same time instead of queueing behind each other.

The target audience follows from that shape. The README names skyblock and SMP as the server types that benefit most, and says the server should have a sizeable player count. A survival world where players scatter to their own bases is the happy case. A lobby where two hundred players stand in one chunk is not: they collapse into one region, and you are left with roughly the performance of a single-threaded server plus the overhead of the region machinery.

Regions tick in parallel, not concurrently

The distinction the README draws between parallel and concurrent is the part most people miss. Regions do not share data and are not expected to share data. Code running in one region cannot access or modify data owned by another region, and the README states plainly that sharing data will cause data corruption. Multithreading in the name does not mean the API became thread-safe; only a few things were made thread-safe to make the design work at all.

So a plugin on Folia must schedule work onto the thread that owns the location or entity it touches. The README points at two schedulers for this: the RegionScheduler and the EntityScheduler, which run a task on the next tick of whichever region owns a location or an entity. The old Bukkit scheduler assumes a single main thread and does not fit. As a rough rule the README suggests a region owns chunk data within about 8 chunks of an event source, but explicitly says this is not guaranteed and that plugins should use thread-check API for correctness. Expect the number of thread context checks to grow over time, even at a performance cost, because bad accesses are meant to fail hard at the source.

Installing Folia and running a first server

Folia is distributed through the PaperMC downloads page, linked from the README badge as papermc.io/downloads/folia. There is no separate installer; you fetch the server jar and launch it the way you would launch a Paper jar. The repository is a patch-based fork, so the top-level tree holds patch.sh, rb.sh and the folia-server and folia-api source trees rather than a runnable build you compile by hand for normal use. The README gives no launch command of its own, so the exact java invocation and memory flags are yours to choose; nothing in the repository prescribes them.

Once the server is up, the setting that matters most lives in the global configuration under the threaded-regions key: threaded-regions.threads controls how many threads the region tick loops get. The README's guidance is to allocate Netty IO, chunk system IO, chunk system workers and any concurrent GC threads first, then give the remainder to threaded-regions.threads, keeping total allocation below 80% of available cores. The 80% ceiling exists because plugins and the server itself may spawn threads you cannot configure or predict. For GC, the README names the -XX:ConcGCThreads=n flag and warns not to confuse it with -XX:ParallelGCThreads=n, since parallel GC threads only run while the application is paused.

If you write plugins rather than run them, the build side is Gradle. The folia-api artifact is published to PaperMC's artifactory, and the README's version badge points at the folia-api maven-metadata path under dev/folia/folia-api. A plugin that should load on Folia needs this in its plugin.yml:

folia-supported: true

Without that key the plugin is not loaded at all.

Plugin compatibility starts at zero

The README does not hedge here. It says there is no more main thread, that every single plugin that exists will require some level of modification, and that expectations for compatibility should be at 0. It also says that basically zero Paper-compatible plugins will be compatible with Folia, with plans to add API that would let Folia plugins also run on Paper.

Even the loading rule is a hard gate rather than a warning. Only plugins whose authors explicitly marked them with folia-supported: true in plugin.yml are loaded. Everything else is skipped. That is a deliberate choice: a plugin that schedules tasks on the Bukkit scheduler or touches another region's data would not degrade gracefully, it would corrupt state. Failing to load is the safer outcome, but it means your plugin list, not your hardware, is usually the first thing that decides whether Folia is viable for you.

There is a second failure mode that has nothing to do with plugins. Because regions tick in parallel and do not share data, any plugin-held state that was implicitly protected by single-threaded execution becomes a race. The README notes that multithreading of any kind introduces possible race conditions in plugin-held data. A plugin can pass the folia-supported flag and still be wrong if its author did not audit shared state.

Sizing threads on a 16-core machine

The README gives a rough starting point drawn from a test server that peaked at around 330 players, and labels it as an estimation that will need tuning. The allocations are expressed per 200 to 300 players: roughly 4 Netty IO threads, 3 chunk system IO threads, and, if the world is pre-generated, about 2 chunk system worker threads. For chunk system workers on a world that is not pre-generated, the README offers no guess at all; on the test server 16 threads were given and chunk generation was still slow at around 300 players.

GC threads count toward the budget too. The README warns not to confuse -XX:ConcGCThreads=n with -XX:ParallelGCThreads=n, because parallel GC threads only run while the application is paused and should not be counted. Whatever remains under the 80% ceiling goes to threaded-regions.threads.

The honest reading of this section is that Folia does not have a recommended configuration, it has a method. You pre-generate the world to cut the worker count, you count every thread pool you can see, you stay under 80%, and then you tune against what you actually observe. The README says plainly that the thread allocation will very likely not be ideal on the first try. Hardware guidance is at least 16 cores, not threads.

Folia against Paper and Purpur

Paper is the upstream Folia patches against, and the README states Folia will not be merged into Paper for the foreseeable future. The difference is architectural, not a matter of tuning: Paper keeps one main thread and scales by making that thread's work cheaper, while Folia removes the thread and scales by running independent regions side by side. That is why the compatibility story inverts. A plugin written for Paper runs on Paper; on Folia it is not loaded unless marked, and even then it needs to use the region and entity schedulers.

Purpur is a Paper fork that changes gameplay and configuration defaults rather than the threading model, so a plugin that works on Paper generally works on Purpur. Choosing between them is choosing between gameplay options and regionised ticking. If your bottleneck is that players are spread out and one thread cannot keep up, Paper and Purpur cannot fix that by configuration. If your bottleneck is anything else, Folia adds a plugin compatibility problem without removing the original one.

Licence, upgrades and maintenance cost

Folia is GPL-3.0. The repository carries a separate PATCHES-LICENSE file alongside the main licence, which is consistent with its structure as a patch-based fork of Paper: the patches are the project's own contribution and sit on top of upstream code. If you redistribute a modified server jar, read both files rather than assuming the single GPL-3.0 identifier covers every part of the tree. This is not legal advice.

Upgrade cost is where a fork of a fork gets expensive. Folia tracks a Paper branch, and the default branch here is ver/26.2.x, so version bumps mean rebasing patches onto a new upstream. The README says Folia is its own project and will not be merged into Paper for the foreseeable future, which means that rebase work does not go away. On the operations side, every server upgrade is also a plugin compatibility re-check, because a plugin marked folia-supported for one version is not automatically correct for the next. The last push to the repository was on 2026-09-22.

Editorial conclusion

Adopt Folia only if your server spreads players across the world, you have at least 16 cores, and your plugin set has been explicitly marked folia-supported: true in each plugin.yml. Do not adopt it for a hub, minigame or heavily plugin-driven server, or on a small VPS, because there is no main thread and unmarked plugins are not loaded at all. Before committing, verify three things: that every plugin you need carries the folia-supported flag, that threaded-regions.threads plus your Netty, chunk system and GC thread allocations stay under 80% of available cores, and that your world is pre-generated so chunk generation does not compete with ticking.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. PaperMC/Folia on GitHub
4. README