Skip to main content
When contributing to Paper or testing unreleased API changes, you need to publish the Paper API to your local Maven repository to use it in your plugins.

​
Why Publish Locally?

Publishing to Maven Local is useful when you:
  • Are developing a Paper API feature or fix
  • Want to test API changes before they’re released
  • Need to verify your plugin works with upcoming Paper versions
  • Are contributing to the Paper project

​
Publishing Paper to Maven Local

1

Navigate to Paper source

Clone the Paper repository and navigate to the root directory:
cd /path/to/Paper
2

Apply patches

Apply the Paper patches to prepare the source:
./gradlew applyPatches
This applies all Paper modifications to the Minecraft source files.
3

Publish to Maven Local

Build and install Paper to your local Maven repository:
./gradlew publishToMavenLocal
This command:
  • Compiles the Paper API and Server
  • Installs them to ~/.m2/repository/
  • Makes them available to all local projects

​
Using the Local Paper API

After publishing, configure your plugin to use the local Maven repository.

​
Gradle Configuration

Add mavenLocal() to your build.gradle.kts:
build.gradle.kts
repositories {
    mavenLocal() // Add this FIRST
    maven {
        url = uri("https://repo.papermc.io/repository/maven-public/")
    }
}

dependencies {
    compileOnly("io.papermc.paper:paper-api:1.21.11-R0.1-SNAPSHOT")
}
Gradle checks repositories in declaration order. Place mavenLocal() before the Paper repository to ensure your local build is used instead of the published version.

​
Maven Configuration

Maven automatically checks the local repository (~/.m2/repository/) before remote repositories, so no configuration changes are needed. Just ensure your dependency version matches the locally published version:
pom.xml
<dependency>
    <groupId>io.papermc.paper</groupId>
    <artifactId>paper-api</artifactId>
    <version>1.21.11-R0.1-SNAPSHOT</version>
    <scope>provided</scope>
</dependency>

​
Important Considerations

Remove mavenLocal() when finished testing.Using Maven Local in production builds can cause issues:
  • Builds become non-reproducible on other machines
  • CI/CD pipelines may fail
  • Team members may get different versions
See the Gradle documentation for more details.

​
Cleaning Up

To remove the locally published Paper API:

​
Linux/macOS

rm -rf ~/.m2/repository/io/papermc/paper/

​
Windows

Remove-Item -Recurse -Force $env:USERPROFILE\.m2\repository\io\papermc\paper\
After cleaning up, your build tools will fetch Paper from the official repository again.

​
Development Workflow

Here’s a typical workflow when developing with local Paper changes:
1

Make changes to Paper

Modify the Paper API or implementation in the Paper source directory.
2

Rebuild and publish

./gradlew applyPatches publishToMavenLocal
3

Test in your plugin

Rebuild your plugin to pick up the changes:
./gradlew clean build
4

Iterate

Repeat steps 1-3 until your changes work correctly.
5

Clean up

Remove mavenLocal() from your plugin’s build configuration before committing.

​
Troubleshooting

​
Changes not appearing

If your plugin doesn’t pick up local changes:
  1. Verify the version numbers match exactly
  2. Run ./gradlew clean build in your plugin
  3. Check that mavenLocal() appears before other repositories
  4. Ensure you ran publishToMavenLocal after making changes

​
Build cache issues

Gradle may cache dependencies. Force a refresh: 
./gradlew build --refresh-dependencies

​
WSL2 Performance

If building on Windows is slow, use WSL2 for significantly better performance. See the Paper CONTRIBUTING.md for setup instructions.

​
Next Steps

Once you’ve verified your changes work:
  1. Submit a pull request to the Paper repository
  2. Follow the contribution guidelines
  3. Wait for the changes to be merged and released
  4. Update your plugin to use the official release

Build docs developers (and LLMs) love

Get started for freeTalk to us