Open-source project
PaperMC/Folia avatar
PaperMC/Folia

Folia gives every chunk region its own tick thread, and plugins must follow

Fork of Paper which adds regionised multithreading to the dedicated server.

4,738 stars650 forksShellGPL-3.0

At a glance

What is it?
Folia is a Paper fork that deletes the main thread and ticks independent chunk regions in parallel. The gain is real for sparse SMP and skyblock servers with many cores, and the cost is that plugin authors must rewrite anything that assumed a single thread.
Who is it for?
Adopt Folia if you run a skyblock or SMP server with players spread across the map and you have at least 16 real cores to hand. Do not adopt it if your plugin set is fixed, because the server loads only plugins whose plugin.yml carries folia-supported: true.
Can I use it commercially?
Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
Is it still maintained?
Yes. The repository last received commits 17 days ago.
What is it written in?
Mainly Shell, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 14, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • PaperMC/Folia4,738 ★ · +367
Star history
Repository2026-09-232026-11-14
PaperMC/Folia4.4k4.7k

367 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

There is no main thread left to schedule against

Folia starts from Paper and removes the single thread that runs the whole server loop. Chunks that sit near each other are grouped into an independent region, and each region carries its own tick loop running at the regular 20 ticks per second. Those loops are executed in parallel on a thread pool, so a region is effectively its own main thread. That is the whole architectural change, and everything else in the project follows from it.

The consequence for a player is straightforward. On a server where players are spread across a large map, Folia creates many separated regions and ticks all of them at once on a pool whose size you configure. On a server where everyone stands in the same village, there is one busy region and the parallelism buys nothing, because there is nothing else to run alongside it. The README names the server types that benefit: skyblock and SMP, where players are naturally spread out and the player count is sizeable.

Folia is not a fork that will fold back into Paper. The README states plainly that this will not be merged into Paper for the foreseeable future, so the region model is a permanent fork policy rather than a feature branch you might later get upstream.

Threads, regions and the 80% core ceiling

Sizing a Folia server is the part the project is most opinionated about, and the numbers come from a test server that peaked near 330 players, which the README calls a very rough estimate and a starting point.

The advice starts with hardware: at least 16 cores, and the README is explicit that this means cores rather than threads. On top of that, budget per 200 to 300 players. Netty IO gets about 4 threads, chunk system IO about 3, and chunk system workers about 2 if the world is pre-generated. Garbage collection threads count too, and the README singles out the flag that decides them: -XX:ConcGCThreads=n. It warns you not to confuse that with -XX:ParallelGCThreads=n, because parallel GC threads only run while the application is paused during collection and so should not be counted against the budget.

Whatever cores remain, up to 80 percent allocation, go to tick threads. That ceiling is not arbitrary. Plugins and the server itself spawn threads you cannot configure or predict, so filling every core with tick threads leaves nothing for them. The remaining figure is set under global config as threaded-regions.threads. The README also states the honest part: the whole scheme is a guess based on player count, and you will still need to tune it against the thread usage you actually observe.

Pre-generating the world is what makes chunk workers tractable

If you take one recommendation from the README seriously, take this one. The project recommends pre-generating the world, because pre-generation greatly reduces the number of chunk system worker threads required.

Without pre-generation there is no useful guess at all. The README is unusually direct about it: on the test server, 16 chunk generation worker threads still produced slow generation at around 300 players, so the number is unknown rather than merely uncertain. That is a hard ceiling on how you can tune the ungenerated case, and it points at where the cost lives. Generation is not something a bigger thread pool solves.

The README's badges point readers at the PaperMC downloads page for Folia and at the GitHub Actions workflow for build output. The server is the same Java application you already run, and the configuration you will actually edit after the first boot is the global config file where the region thread count lives.

Only plugins declaring folia-supported are loaded at all

Folia does not attempt partial compatibility. Because the main thread is gone, the README expects every existing plugin to need some level of modification, and states that expectations for compatibility should be set at 0.

Enforcement is mechanical rather than advisory. Only plugins whose author has explicitly marked them will load. The mechanism is a single line in the plugin's plugin.yml: folia-supported: true. No flag, the server skips the plugin. This is the filter that keeps a broken world state from loading code that assumes a main thread, and it also means a plugin that happens to work perfectly is still ignored until its author signs off.

That has an upside for operators. The flag records the author's compatibility declaration; it does not prove the plugin is free of concurrency bugs or guarantee world safety. It has a downside too. Coverage depends entirely on how many plugin authors have made the change, so the practical size of the ecosystem is the deciding factor for anyone evaluating the fork, and the README does not claim it is large.

Regions tick in parallel, not concurrently, and sharing data corrupts it

The design rule underneath the schedulers is worth reading closely. Regions tick in parallel, and the README says not concurrently. They do not share data, they do not expect to share data, and sharing data will cause corruption. Code running in one region may never, under any circumstance, read or modify data belonging to another region.

The README pushes back on the inference that comes with the name: multithreading in the name does not mean anything is now thread-safe. Only a few specific things were made thread-safe to make the model work. The stated direction is that thread context checks will keep growing, and the author accepts a performance penalty for that, because the alternative is a platform that is buggy and hard to debug. Bad access has to fail hard at the source.

Thread safety covers server-owned data only. A region owns roughly 8 chunks from the source of an event, so a plugin can expect to touch the chunks around the block a player just broke. But the README says this is not guaranteed and points at a thread-check API as the correct path. Plugin data is explicitly outside the guarantee: it is entirely unrelated to the entity, chunk and POI data the region owns, and it follows ordinary multithreading rules.

RegionScheduler and EntityScheduler replace the Bukkit Scheduler

The Bukkit Scheduler assumes a single main thread, so it cannot work here. Folia's answer is a pair of schedulers that target ownership instead of a global thread: RegionScheduler and EntityScheduler. Both schedule a task for the next tick of whichever region owns a given location or a given entity.

The interesting part is what the README says about portability. These schedulers could be implemented on regular Paper, except that there they schedule onto the main thread. In both cases execution happens on the thread that owns the location or the entity. The README frames Paper itself as one giant region covering all chunks in all worlds, which makes the region model a generalisation rather than something with no Paper equivalent. Where that API should live, in Paper itself or in Paperlib, is stated as undecided.

Events, commands and callbacks are called in parallel, by necessity. The README rejects the synchronous alternative because it opens deadlock issues and handicaps performance. There is no general escape hatch, so plugin code has to reason about which data it touches.

Where Folia loses to Paper, Purpur and unmodified setups

The honest comparison is with Paper and its derivatives, including Purpur. Those retain a main server thread and generally support a broader existing plugin ecosystem, though compatibility still depends on each plugin and server version. They scale by improving one thread and by adding optimisation work inside it. Folia scales by spending more cores across many tick loops, and pays for that with a compatibility wall that Paper does not have.

That is the real difference in approach. Paper optimises a single timeline, Folia removes the timeline and pays for the split in plugin compatibility. Neither claims to subsume the other, and Folia is not headed for an upstream merge.

Two conditions decide it. If your player count is modest or concentrated in one area, Folia leaves tick threads idle and Paper carries none of the problems. If your server must run a specific plugin ecosystem, Folia's filter means the decision is made by the plugin authors, not by you. The repository's last push was on 2026-10-30 and it is not archived, so the fork itself is current, with no GitHub releases published.

Editorial conclusion

Adopt Folia if you run a skyblock or SMP server with players spread across the map and you have at least 16 real cores to hand. Do not adopt it if your plugin set is fixed, because the server loads only plugins whose plugin.yml carries folia-supported: true. Verify first that every plugin you need declares that flag, then pre-generate the world so chunk system workers are not the bottleneck. Check the README yourself: its plugin compatibility section tells you to set expectations for compatibility at 0, and its configuration advice is blunt that on an ungenerated world even 16 chunk generation workers were slow at around 300 players. If your plugins are not ready, the Paper line with Purpur is the lower risk path and costs you nothing but the extra cores.

Frequently asked questions

How do I install Folia on a Minecraft server?

The README links to the PaperMC Folia downloads page and to the project's GitHub Actions workflow.

How do I set up Folia for a Minecraft server?

The README recommends pre-generating the world, then sizing threads for a target of 200 to 300 players: about 4 netty IO threads, 3 chunk system IO threads and 2 chunk system workers if pre-generated. Remaining cores up to 80 percent allocation go to tick threads under global config at threaded-regions.threads.

What is Folia in Minecraft?

Folia is a fork of Paper that adds regionised multithreading to the dedicated server. It groups nearby loaded chunks into independent regions, each with its own tick loop at 20TPS, and runs those loops in parallel on a thread pool with no main thread.

Is Folia better than Paper?

Folia trades plugin compatibility for parallelism on many cores. It suits skyblock and SMP servers with spread-out players and at least 16 cores, while Paper keeps the single main thread that existing plugins assume.

Official sources

  1. Issues
  2. License: GPL-3.0
  3. PaperMC/Folia on GitHub
  4. README
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/papermc-folia.svg)](https://hysenlabs.com/projects/papermc-folia)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/papermc-folia.svg)](https://hysenlabs.com/projects/papermc-folia)

Was this useful?