Skip to main content
This guide covers setting up your development environment for contributing to Paper, including IDE configuration, repository setup, and best practices.

​
Requirements

Before starting, ensure you have:
  • Git - Version control system
  • JDK 21 or later - Required for building Paper
    • Adoptium provides builds for most operating systems
    • Paper uses Gradle’s Toolchains feature
  • IntelliJ IDEA (recommended) - Most of the Paper team uses IntelliJ
While other IDEs may work, IntelliJ IDEA is the recommended and officially supported IDE for Paper development.

​
Windows-Specific Setup

If you’re on Windows, WSL 2 (Windows Subsystem for Linux) is highly recommended for significantly faster build and patch times.

​
Setting up WSL 2

WSL 2 is available on Windows 10 version 2004 (build 19041) or higher. Check your version by running winver.
1

Install WSL 2

Follow the official Microsoft WSL installation guide.
2

Install Ubuntu

Install Ubuntu from the Microsoft Store (or your preferred Linux distribution).
3

Install development tools

In your WSL terminal:
sudo apt-get update
sudo apt-get install git -y
Then install JDK 21 from Adoptium.
4

Access WSL files in Windows

You can access your WSL files from Windows File Explorer:
explorer.exe .
Important: Do NOT use the /mnt/ directory in WSL for development. This path accesses Windows files through WSL, which is extremely slow. Always work in your WSL home directory (~) or other native WSL paths.

​
Repository Setup

Use a Personal Fork, Not an OrganizationPaper team members routinely modify PRs for quick fixes and rebases. GitHub prevents modifications to PRs from organization repositories. Always fork Paper to your personal GitHub account.
1

Fork the repository

Fork the PaperMC/Paper repository to your personal GitHub account.
2

Clone your fork

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

Add upstream remote

git remote add upstream https://github.com/PaperMC/Paper.git
This allows you to pull the latest changes from the official repository.
4

Apply patches

./gradlew applyPatches
This creates the paper-server/src/minecraft directory with Paper’s patched Minecraft source.

​
IntelliJ IDEA Configuration

1

Import the project

Open IntelliJ IDEA and import the Paper project as a Gradle project. IntelliJ should automatically detect the Gradle configuration.
2

Disable sync external changes

This is critical for performance during patch operations.Navigate to:
Settings > Appearance & Behavior > System Settings
Disable this option:
  • ☐ Sync external changes: Periodically when the IDE is inactive (experimental)
When this setting is enabled, IntelliJ attempts to reindex files while patches are being applied, causing severe slowdowns and freezes.
3

Disable reopen projects on startup (optional)

To avoid freeze loops when patches fail:Navigate to:
Settings > Appearance & Behavior > System Settings
Disable this option:
  • ☐ Reopen projects on startup
This prevents IntelliJ from automatically opening Paper if patches are in a broken state.
4

Configure Java toolchain

IntelliJ should automatically detect your JDK 21 installation through Gradle’s toolchain configuration.Verify under:
Settings > Build, Execution, Deployment > Build Tools > Gradle
Gradle JVM should be set to JDK 21 or use the Gradle default.

​
IDE Features

IntelliJ IDEA provides excellent support for:
  • Git integration and conflict resolution
  • Gradle task execution
  • Debugging Paper server instances
  • Code navigation in Paper’s patched Minecraft source
  • Automatic code formatting according to Paper’s style

​
Understanding the Project Structure

Paper uses a patch-based development workflow: 
Paper/
├── paper-api/           # Bukkit API implementation
├── paper-server/        # Server implementation
│   └── src/
│       └── minecraft/   # Patched Minecraft source (generated)
├── patches/             # Paper's patch files
│   ├── api/            # API patches
│   ├── server/         # Server patches
│   │   ├── sources/    # Per-file patches
│   │   ├── resources/  # Resource patches
│   │   └── features/   # Feature patches
├── build-data/          # Build configuration
│   └── paper.at        # Access transformers
└── test-plugin/         # Optional test plugin module

​
Important Directories

  • paper-api/ - Changes to the Bukkit API
  • paper-server/src/minecraft/ - Minecraft source modifications (patch-tracked)
  • paper-server/src/main/ - Non-Minecraft server code (regular Git)
  • patches/ - Actual patch files that get applied
Only changes in paper-server/src/minecraft/ use the patch system. Other directories use standard Git tracking.

​
Development Workflow

​
Making Changes

1

Create a feature branch

git checkout -b my-feature-branch
2

Make your changes

  • For API changes: Edit files in paper-api/
  • For Minecraft changes: Edit files in paper-server/src/minecraft/
  • For other server changes: Edit files in paper-server/src/main/
3

Test your changes

./gradlew runDevServer
This runs a development server with your changes without creating a JAR.
4

Rebuild patches

If you modified files in paper-server/src/minecraft/:
./gradlew fixupSourcePatches
./gradlew rebuildPatches
For other changes, commit normally with Git.
5

Commit your changes

git add .
git commit -m "Description of your changes"

​
Modifying Minecraft Patches

For per-file patches (most common):
  1. Make changes to files in paper-server/src/minecraft/
  2. Run ./gradlew fixupSourcePatches
  3. Run ./gradlew rebuildPatches
  4. Commit the updated patch files
See the CONTRIBUTING.md for detailed information on:
  • Handling rebase conflicts
  • Creating feature patches
  • Using fixup commits
  • Patch formatting guidelines

​
Using the Test Plugin

Paper includes an optional test plugin module for testing API changes.
1

Enable the test plugin

Enable it in test-plugin.settings.gradle.kts (generated after running Gradle once).
2

Edit the test plugin

Make changes to test-plugin/src/main/java/.
3

Run with the test plugin

./gradlew runDevServer
The run tasks automatically include the test plugin when enabled.

​
Testing API Changes Locally

To test your Paper changes in external plugins:
1

Publish to Maven Local

./gradlew publishToMavenLocal
2

Configure your plugin project

For Gradle:Add mavenLocal() as the first repository:
repositories {
    mavenLocal()  // Must be first
    maven("https://repo.papermc.io/repository/maven-public/")
}
Remove mavenLocal() when done testing. See the Gradle docs for why.
3

Use Paper in your plugin

Your plugin will now use your locally-built Paper version.

​
Git Workflow Tips

​
Keeping Your Fork Updated

# Fetch latest changes from upstream
git fetch upstream

# Update your main branch
git checkout main
git merge upstream/main

# Rebase your feature branch
git checkout my-feature-branch
git rebase upstream/main

​
Understanding Git Basics

Paper’s patch system is built on Git. If you’re new to Git, review this tutorial: https://git-scm.com/docs/gittutorial

​
Common Issues

​
IntelliJ freezes during patch application

Solution: Disable “Sync external changes” in IntelliJ settings (see IntelliJ IDEA Configuration).

​
Patch conflicts during rebase

See the CONTRIBUTING.md rebase conflict resolution guide.

​
Build fails with “JAVA_HOME not set”

Solution: Ensure JDK 21 is installed and JAVA_HOME points to it: 
export JAVA_HOME=/path/to/jdk-21

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us