Skip to main content
PaperMC welcomes contributions to our projects. This guide will help you get started with contributing to Paper, whether it’s fixing bugs, adding new features, or improving existing functionality.

​
Requirements

Before you begin, ensure you have the following software installed:
1

Install Git

Install git using your package manager:
  • Debian/Ubuntu/WSL: apt install git
  • macOS/Linux: homebrew install git
2

Install Java 21 JDK

Paper requires JDK 21 to build. We recommend Adoptium builds for most operating systems.
Paper uses Gradle’s Toolchains feature, allowing you to build with only JRE 17 or later installed. Gradle will automatically provision JDK 21 for compilation if needed.

​
Docker Setup

If you’re compiling with Docker, use Adoptium’s eclipse-temurin images: 
docker run -it -v "$(pwd)":/data --rm eclipse-temurin:21.0.5_11-jdk bash
Verify the Java version: 
javac -version
# Output: javac 21.0.5

​
Use a Personal Fork

Always use a personal fork, not an organization fork. Paper routinely modifies PRs for quick rebases or minor fixes. Organization repositories prevent Paper from making these modifications, which slows down the review process.

​
Initial Setup

1

Fork the Repository

Create a personal fork of the Paper repository on GitHub.
2

Clone Your Fork

git clone https://github.com/YOUR_USERNAME/Paper.git
cd Paper
3

Apply Patches

Apply the existing patches to set up your development environment:
./gradlew applyPatches
On Windows, remove the ./ from the beginning of gradlew commands: gradlew applyPatches
4

Navigate to Your Working Directory

  • For server changes: cd paper-server
  • For API changes: cd paper-api
Only changes made in paper-server/src/minecraft require working with the patch system.

​
Understanding the Patch System

Unlike the API and its implementation, modifications to Minecraft source files are done through patches. These patches are split into three different sets:
  • sources: Per-file patches to Minecraft classes
  • resources: Per-file patches to Minecraft data files
  • features: Larger feature patches that modify multiple Minecraft classes
The paper-server/src/minecraft directory is not a traditional git repository. Its initial commits are the decompiled and deobfuscated Minecraft source files. Per-file patches are applied on top as a single large commit, followed by individual feature-patch commits.

​
Understanding Git

Since the entire patch structure is based on git, a basic understanding is required. New to git? Check out the official Git tutorial.

​
Platform-Specific Notes

​
Windows Users

Patching and building on Windows is significantly slower than on Unix-based systems. For the best experience, use WSL 2 (Windows Subsystem for Linux).
WSL 2 is available in Windows 10 v2004 (build 19041) or higher. Check your version by running winver in the run window (Windows key + R). Setting up WSL 2:
  1. Follow the official WSL installation guide
  2. Install Ubuntu from the Microsoft Store
  3. Install required tools: 
    sudo apt-get update && sudo apt-get install git -y
  4. Clone the repository and work within WSL
Do not use the /mnt/ directory in WSL! Instead, work within the WSL filesystem (~/) and mount WSL directories in Windows File Explorer.

​
IntelliJ IDEA Tips

For the best development experience with IntelliJ IDEA:
  1. Disable automatic sync under Settings > Appearance & Behavior > System Settings:
    • Disable Sync external changes: Periodically when the IDE is inactive (experimental)
    • This prevents the IDE from attempting to reindex files while patches are applying
  2. Disable project reopening (optional):
    • Disable Reopen projects on startup to avoid freeze loops

​
Next Steps

Now that you have your development environment set up, you’re ready to start making changes:

Build docs developers (and LLMs) love

Get started for freeTalk to us