Packet Control for Minecraft Servers

Yes, ProtocolLib is safe. It has been a core part of the Bukkit/Spigot/Paper plugin ecosystem since 2012, maintained by Dan Mulloy (dmulloy2) on GitHub with full source code transparency. The project has over 1,300 GitHub stars, 309 forks, and more than 625,000 downloads on its latest release alone. Thousands of production Minecraft servers run ProtocolLib daily without any security concerns.

ProtocolLib is distributed as a single JAR file (approximately 10.25 MB for version 5.4.0) licensed under GPL-2.0. Because the entire codebase is open source on GitHub, anyone can audit the code for malicious behavior. The plugin does not collect telemetry, phone home to external servers, or modify your server files beyond its own data folder. Major anti-cheat plugins like GrimAC and popular tools like Citizens, LibsDisguises, and HolographicDisplays all depend on ProtocolLib, which speaks to the level of trust it has earned in the community.

• Download only from official sources: GitHub Releases, Hangar, or our download section
• Avoid third-party download sites that may bundle modified JARs with malware
• Verify the JAR file size matches the official release (around 10.25 MB for v5.4.0)

Pro tip: After downloading, you can verify the JAR integrity by checking its SHA-256 hash against the one listed on the GitHub Releases page. This confirms the file has not been tampered with.

For the latest official version, visit our download section.

The official ProtocolLib download is hosted on GitHub Releases at github.com/dmulloy2/ProtocolLib/releases. The plugin is also distributed through Hangar (PaperMC’s plugin repository) and BukkitDev. These are the only three legitimate sources maintained or approved by the developer.

Version 5.4.0, released on August 7, 2025, is the current stable release. The JAR file is approximately 10.25 MB and requires Java 17 or newer. You should never download ProtocolLib from random file-sharing sites, forums with rehosted files, or any source that asks you to disable your antivirus first. Those are red flags for tampered copies.

• GitHub Releases: The primary source, hosted at github.com/dmulloy2/ProtocolLib/releases
• Hangar (PaperMC): hangar.papermc.io/dmulloy2/ProtocolLib — 20,595+ downloads
• BukkitDev: dev.bukkit.org/projects/protocollib
• Maven Central: For developers adding ProtocolLib as a build dependency (net.dmulloy2:ProtocolLib:5.4.0)

Pro tip: Bookmark the GitHub Releases page directly. When a new Minecraft version drops, the updated ProtocolLib build usually appears there first, sometimes days before it reaches Hangar or BukkitDev.

You can grab the latest version from our download section, which links directly to the official GitHub release.

ProtocolLib contains zero malware, spyware, or adware. The entire source code is publicly available on GitHub under the GPL-2.0 license, meaning every line of code can be reviewed by anyone. The project has been actively maintained since 2012 with hundreds of contributors reviewing and submitting changes through pull requests.

Unlike closed-source plugins where you have to trust the developer blindly, ProtocolLib’s open nature means the Minecraft developer community continuously audits the codebase. The plugin operates entirely within the server JVM and only interacts with Minecraft network packets. It does not access your filesystem outside its own plugin folder, does not open external network connections, and does not collect any form of user data or analytics.

• Open-source GPL-2.0 license — full code transparency on GitHub
• No telemetry, no analytics, no external connections
• Audited by thousands of developers who depend on it for their own plugins
• Trusted by enterprise-grade plugins like GrimAC, Citizens, and LibsDisguises

Pro tip: If you are running a public-facing server and want extra assurance, build ProtocolLib from source yourself using mvn clean package on the GitHub repository. This guarantees you are running exactly what the source code says.

Learn more about ProtocolLib’s architecture in our features overview.

ProtocolLib supports Minecraft versions 1.8 through 1.21.8. That covers nearly every major Minecraft release from the past decade. Version 5.4.0 is tested and confirmed working on the latest Minecraft builds as of August 2025.

The plugin works on three server platforms: Bukkit, Spigot, and Paper (including Paper forks like Purpur and Folia with some caveats). Each new Minecraft version typically requires a ProtocolLib update because the internal packet structure changes between versions. Dan Mulloy and the contributor community usually push compatible builds within days of a major Minecraft release, though snapshot support may lag behind.

• Minecraft 1.8 – 1.12.2: Supported via older ProtocolLib builds (4.x branch)
• Minecraft 1.13 – 1.20.6: Fully supported with ProtocolLib 5.x releases
• Minecraft 1.21 – 1.21.8: Supported by ProtocolLib 5.4.0
• Server platforms: Bukkit, Spigot, Paper, and most Paper forks

When you see a console warning that says “Version (MC: X.X.X) has not yet been tested!” during startup, that usually means ProtocolLib will still function correctly but has not been formally validated for that specific build. Most server operators report no issues when they see this message.

Pro tip: If you are running a very new Minecraft version and the stable release does not support it yet, check the GitHub Actions tab for development builds that may already include the fix.

Check our system requirements section for the full compatibility matrix.

Yes, ProtocolLib runs on any operating system that supports Java 17 or newer. Because it is a Java-based plugin, it is completely platform-independent. Windows, macOS, Linux (Ubuntu, Debian, CentOS, Arch), and even FreeBSD all work without issues.

The JAR file is identical across all platforms — there is no separate “Windows version” or “Linux version.” You download the same ProtocolLib.jar (approximately 10.25 MB) and drop it into your server’s plugins/ folder regardless of your OS. The only requirement is that your server runs Java 17 or newer, which is also the minimum for Minecraft 1.20.5+ servers.

• Windows: Works with Java 17+ from Oracle, Adoptium, or Amazon Corretto
• macOS: Works on both Intel and Apple Silicon Macs with Java 17+
• Linux: Works on all major distributions — most production Minecraft servers run on Ubuntu or Debian
• Docker/containers: Works in containerized Minecraft servers using images like itzg/minecraft-server

Pro tip: On Linux servers, use Adoptium Temurin or Amazon Corretto for the best Minecraft performance. These JDK distributions include optimizations that reduce garbage collection pauses, which directly improves tick consistency when ProtocolLib is processing packets.

See the full Java and server requirements in our system requirements.

ProtocolLib requires Java 17 or newer and a Bukkit, Spigot, or Paper-based Minecraft server. There are no specific CPU, RAM, or disk requirements beyond what your Minecraft server already needs. The plugin itself adds minimal overhead to server resources.

The JAR file is 10.25 MB and uses a small amount of additional RAM at runtime — typically under 20 MB for most server configurations. CPU usage depends entirely on how many packet listeners are registered by your other plugins and how much traffic your server handles. A server with 50 players and 5 ProtocolLib-dependent plugins will use noticeably more resources than a 10-player server with 1 dependent plugin, but the per-packet processing cost is measured in microseconds.

• Java: Version 17 or newer (required, not optional)
• Server software: Bukkit, Spigot, Paper, or compatible forks
• RAM overhead: Roughly 10-20 MB additional beyond your base server allocation
• Disk space: 10.25 MB for the JAR plus a small config/data folder
• Minecraft version: 1.8 through 1.21.8

Pro tip: If you are running a high-player-count server (100+ players) with many packet listeners, allocate at least 512 MB extra RAM beyond your normal server allocation. Use /protocol timings in-game to monitor which listeners consume the most processing time, and optimize or remove slow ones.

View the complete requirements table in our system requirements section.

Yes, ProtocolLib is 100% free. There is no paid version, no premium tier, no subscription, and no hidden costs. The plugin is released under the GNU General Public License v2.0 (GPL-2.0), which means it is free to download, use, modify, and redistribute.

You can use ProtocolLib on as many servers as you want — personal, commercial, or enterprise — without paying anything. There are no player limits, no feature restrictions, and no time-limited trials. The GPL-2.0 license also means that any modified version of ProtocolLib must remain open source, which prevents anyone from creating a proprietary fork.

• Free for personal and commercial Minecraft servers
• No player count limits or feature gates
• No registration, account creation, or license key required
• GPL-2.0: you can modify the source code, but modified versions must also be open source

Pro tip: While ProtocolLib itself is free, some plugins that depend on it (like premium anti-cheat or cosmetics plugins) are paid. ProtocolLib is the library — think of it as the foundation that other plugins build on top of. The library costs nothing; some of the tools built with it may have their own pricing.

Download ProtocolLib for free from our download section.

ProtocolLib uses the GNU General Public License v2.0 (GPL-2.0). This is one of the most permissive copyleft licenses available, and it gives you broad rights to use, study, modify, and distribute the software.

Under GPL-2.0, you can freely modify ProtocolLib’s source code for your own server. If you distribute your modified version to others (for example, sharing a custom fork publicly), that fork must also be released under GPL-2.0 with the source code available. For private server use where you never distribute the modified JAR, you have no obligation to share your changes. Many large Minecraft networks run internally patched versions of ProtocolLib without any licensing issues because they keep those modifications private.

• Use: Unlimited, on any number of servers, for any purpose
• Modify: Yes, modify freely for private use
• Distribute: Yes, but distributed copies must include source code under GPL-2.0
• Commercial use: Fully permitted

Pro tip: If you are a plugin developer building on top of ProtocolLib, your plugin does NOT need to be GPL-2.0. ProtocolLib is a runtime dependency loaded separately, so your plugin’s license is independent. This is why premium plugins on SpigotMC can depend on ProtocolLib without being forced to open source their own code.

Read more about ProtocolLib’s open-source development on our features page.

Installing ProtocolLib takes about 60 seconds. Download the ProtocolLib.jar file from the official GitHub Releases page (or from our download section), place it in your server’s plugins/ folder, and restart the server. There is no installer, no setup wizard, and no configuration needed.

ProtocolLib works out of the box with zero configuration for most servers. The JAR file size is approximately 10.25 MB for version 5.4.0. Your server must be running Bukkit, Spigot, or Paper with Java 17 or newer. If you are running an older Java version, the plugin will fail to load with a class version error.

1. Download ProtocolLib.jar from the download section or directly from GitHub Releases
2. Stop your Minecraft server if it is currently running (do not use /reload)
3. Copy the JAR file into your server’s plugins/ folder
4. Start the server — ProtocolLib will generate its config in plugins/ProtocolLib/
5. Verify the plugin loaded by typing /plugins in the console — ProtocolLib should appear in green

Pro tip: Never install ProtocolLib using a plugin reloader like PlugMan. ProtocolLib explicitly does not support hot-reloading and will throw a “ProtocolLib does not support plugin reloaders” error. Always do a full server restart when installing or updating.

For a detailed walkthrough, check our Getting Started guide.

The most common ProtocolLib installation error is “INTERNAL ERROR: Cannot load ProtocolLib” in the server console. This almost always means either a Java version mismatch or a Minecraft version that has not been formally tested yet. The fix depends on which specific error you see in the stack trace.

ProtocolLib 5.4.0 requires Java 17 at minimum. If you are running Java 8 or Java 11, you will get an UnsupportedClassVersionError. Separately, when a new Minecraft version drops, you may see the warning “Version (MC: X.X.X) has not yet been tested!” — this warning is usually harmless, but if the plugin actually fails to load afterward, you need a newer ProtocolLib build.

1. Check your Java version: run java -version in the terminal — it must say 17 or higher
2. Look at the full error in the console log, not just the first line — the actual cause is usually 10-20 lines down
3. If you see FieldAccessException: a dependent plugin needs updating, not ProtocolLib itself
4. If you see IllegalAccessError: a plugin has bundled ProtocolLib classes inside its own JAR — contact that plugin’s developer
5. If you see NoClassDefFoundError: BaseComponent: switch from CraftBukkit to Spigot or Paper
6. Make sure you do not have two copies of ProtocolLib in the plugins/ folder (check for old versions)

Pro tip: Run /protocol dump after the server starts to see which plugins registered packet listeners with ProtocolLib. If a specific plugin causes the crash, you can isolate it by removing plugins one at a time and restarting until the error disappears.

More troubleshooting steps in our Getting Started guide.

When ProtocolLib appears red in the /plugins list, it means the plugin failed to enable during server startup. This is one of the most commonly reported issues on Reddit’s r/admincraft, and it usually comes down to a Java version problem, a corrupted JAR, or a conflict with another plugin.

Paper/Purpur servers on Minecraft 1.20+ are the most frequent environment where this occurs, typically because the server operator updated Minecraft but forgot to update ProtocolLib. The plugin checks the Minecraft version on startup and may refuse to enable if it detects an untested version. Check your server’s logs/latest.log file for the exact error message — the console output often gets truncated.

1. Open logs/latest.log and search for “ProtocolLib” — find the actual error, not just the “failed to load” line
2. Confirm you have only ONE copy of ProtocolLib.jar in plugins/ (delete any old versions)
3. Verify Java 17+ with java -version
4. Download the latest ProtocolLib release from GitHub and replace the existing JAR
5. Do a full server restart (not /reload)

Pro tip: If ProtocolLib loads fine by itself but fails when other plugins are present, you likely have a plugin conflict. Remove all other plugins, start with only ProtocolLib, then add plugins back one at a time. Binary search: add half your plugins, see if it breaks, narrow down from there.

Check the full system requirements to make sure your setup meets all prerequisites.

This is expected behavior. Every major Minecraft version changes the internal packet structure, which means ProtocolLib needs an update to match. When you upgrade your server from, say, 1.20.4 to 1.21.x, the old ProtocolLib JAR will likely fail because it does not recognize the new packet formats.

Dan Mulloy and the contributor team typically release a compatible ProtocolLib build within a few days of a major Minecraft release. For minor updates (1.21.1 to 1.21.2), ProtocolLib usually works without changes. The “Version (MC: X.X.X) has not yet been tested!” warning does not necessarily mean it is broken — it just means the version has not been formally validated.

1. Go to github.com/dmulloy2/ProtocolLib/releases and check if a new release is available
2. If no stable release exists yet, check the GitHub Actions tab for development builds
3. Download the latest JAR, replace the old one in plugins/, and restart
4. If no updated build exists at all, wait a few days or temporarily downgrade your Minecraft server to the previous version

Pro tip: Before updating your Minecraft server, always check the ProtocolLib GitHub Issues page and the PaperMC Discord for reports about compatibility. Updating your server on day one of a Minecraft release almost guarantees ProtocolLib will not have a stable build ready yet. Wait 3-5 days for plugin ecosystem updates.

Download the latest compatible version from our download section.

This error appears when you use a plugin reloader (like PlugMan, ServerUtils, or the built-in /reload command) to reload ProtocolLib. The solution is straightforward: stop using reloaders with ProtocolLib. Always do a full server restart instead.

ProtocolLib hooks deeply into the Minecraft server’s Netty network pipeline during initialization. When a reloader tries to unload and reload it at runtime, the internal state becomes inconsistent. Packet listeners from other plugins lose their registrations, injected channel handlers get orphaned, and the whole packet interception system breaks down. This is by design — the developer has explicitly stated that hot-reloading is not and will not be supported.

1. Stop using /reload, /plugman reload ProtocolLib, or any similar reload command
2. If you already triggered the error, do a full server stop and start (not restart through the panel — a clean stop/start)
3. For development servers where you need quick iteration, restart only the server process instead of reloading individual plugins
4. Consider using a Paper server with the -Dpaper.disableOldApiSupport=true flag, which catches reload-related issues earlier

Pro tip: If you absolutely need fast plugin iteration during development, use a test server with minimal plugins where a full restart takes under 10 seconds. On production servers, schedule restarts during low-traffic hours and use a restart script that backs up the world first.

See our Getting Started guide for proper installation practices.

Updating ProtocolLib is the same process as installing it. Download the latest JAR from GitHub Releases, replace the old file in your plugins/ folder, and restart the server. There is no built-in auto-update mechanism.

The current latest version is 5.4.0 (released August 7, 2025), weighing approximately 10.25 MB. Your existing ProtocolLib configuration and data will be preserved during the update — the plugin reads its settings from the plugins/ProtocolLib/ folder, and upgrading the JAR does not touch that folder. You do not need to delete old config files unless the release notes specifically mention a breaking config change (which is rare).

1. Check the current version on your server with /version ProtocolLib
2. Visit our download section or the GitHub Releases page to see if a newer version is available
3. Stop the server completely
4. Delete the old ProtocolLib.jar from plugins/
5. Copy the new JAR into plugins/
6. Start the server and verify with /plugins

Pro tip: Keep one previous version of ProtocolLib.jar saved outside the plugins folder (rename it something like ProtocolLib-5.3.0-backup.jar). If the new version causes issues with your plugin setup, you can quickly roll back by swapping the JAR files and restarting.

Get the latest version from our download section.

ProtocolLib 5.4.0, released on August 7, 2025, adds support for Minecraft 1.21.8 and includes several bug fixes and internal improvements. This release extends the already broad compatibility range of 1.8 through 1.21.8, making it the most version-compatible release to date.

The 5.x branch of ProtocolLib introduced significant architectural changes compared to the older 4.x branch. It dropped support for Java versions below 17, moved to Maven Central for dependency management (artifact net.dmulloy2:ProtocolLib:5.4.0), and rewrote portions of the packet wrapping system to handle the increasingly complex Minecraft protocol. The 5.x series also improved performance for high-traffic servers by optimizing how packet listeners are dispatched.

• Added Minecraft 1.21.8 compatibility
• Bug fixes for edge cases in packet serialization
• Improved stability on Paper and Purpur server forks
• Published on Maven Central for easier dependency management
• Continued support for the full 1.8 – 1.21.8 version range

Pro tip: For developers, the move to Maven Central means you no longer need to add the dmulloy2 repository to your pom.xml or build.gradle. Just use the standard Maven Central coordinates: net.dmulloy2:ProtocolLib:5.4.0 with scope provided.

Download the latest version from our download section.

For most Minecraft server operators, use whichever library your plugins require. If your plugins depend on ProtocolLib, install ProtocolLib. If they depend on PacketEvents, install PacketEvents. Many servers run both simultaneously without problems.

For plugin developers choosing a library, the answer is more nuanced. ProtocolLib is the mature, battle-tested option with over a decade of history and broad ecosystem support. PacketEvents is the newer alternative with a more modern API design, cross-platform support (Spigot, Velocity, Fabric, and BungeeCord), and native async packet handling on Netty threads. ProtocolLib processes packets synchronously on the server thread by default, while PacketEvents operates asynchronously, which can offer better performance on high-traffic servers.

• ProtocolLib: Mature (since 2012), huge ecosystem, Bukkit/Spigot/Paper only, synchronous by default, 625k+ downloads on latest release
• PacketEvents: Newer, modern API, cross-platform (Spigot + Velocity + Fabric + BungeeCord), async on Netty threads, growing rapidly
• Ecosystem: Most existing plugins use ProtocolLib (Citizens, LibsDisguises, HolographicDisplays). Newer plugins increasingly adopt PacketEvents (GrimAC supports both)
• Can you run both? Yes. They hook into different parts of the network stack and generally do not conflict

Pro tip: If you are starting a new plugin project in 2025, PacketEvents offers a cleaner developer experience with better documentation and cross-platform reach. If you are maintaining an existing plugin or need maximum backward compatibility, stick with ProtocolLib. Do not rewrite a working ProtocolLib integration just to switch libraries.

See what makes ProtocolLib stand out in our features section.

Yes, ProtocolLib is designed to coexist with other plugins, including other packet libraries. Running ProtocolLib and PacketEvents simultaneously is a common configuration on servers that use plugins depending on each library. ViaVersion, which handles cross-version protocol translation, also runs alongside ProtocolLib without issues on most setups.

The only scenario where conflicts arise is when two plugins try to modify the same packet type in incompatible ways. For example, if Plugin A cancels a chat packet and Plugin B tries to modify it, the outcome depends on listener priority. ProtocolLib handles this through its priority system (LOWEST, LOW, NORMAL, HIGH, HIGHEST, MONITOR), similar to Bukkit’s event priority model. As long as plugin developers set appropriate priorities, multiple listeners on the same packet type work correctly.

• ProtocolLib + PacketEvents: Generally safe, no known systemic conflicts
• ProtocolLib + ViaVersion: Works well, commonly used together on cross-version servers
• ProtocolLib + anti-cheats (GrimAC, Vulcan): Supported, anti-cheats are among the heaviest ProtocolLib users
• Multiple ProtocolLib-dependent plugins: No issues — this is the normal use case

Pro tip: Use /protocol listeners to see every registered packet listener on your server, grouped by packet type and priority. This command is invaluable for debugging unexpected packet behavior when running many plugins together.

Learn more about ProtocolLib’s API design in our features overview.

Add ProtocolLib as a provided dependency in your Maven or Gradle build file, declare it in your plugin.yml as a dependency, and use the ProtocolLibrary.getProtocolManager() method to access the packet API. From there, you register PacketListener implementations to intercept specific packet types.

The core workflow involves three steps: get the ProtocolManager instance, create a PacketAdapter (which implements PacketListener), and register it. The PacketAdapter lets you specify which packet types to listen for and whether to intercept incoming (client-to-server) or outgoing (server-to-client) packets. Inside the listener callback, you receive a PacketEvent containing a PacketContainer — a type-safe wrapper around the raw packet with indexed read/write methods like getIntegers(), getDoubles(), and getStrings().

1. Add to your pom.xml: <dependency> net.dmulloy2:ProtocolLib:5.4.0 (scope: provided)</dependency>
2. Add to plugin.yml: depend: [ProtocolLib] or softdepend: [ProtocolLib]
3. Get the manager: ProtocolManager manager = ProtocolLibrary.getProtocolManager();
4. Create a listener: extend PacketAdapter and override onPacketReceiving or onPacketSending
5. Register it: manager.addPacketListener(yourListener);

Pro tip: Always set your listener priority appropriately. Use NORMAL for most cases, HIGH if you need to modify packets after other plugins see them, and MONITOR if you only want to observe without modifying. Never modify packets in a MONITOR listener — other plugins assume MONITOR listeners are read-only.

See code examples in our Getting Started guide.

ProtocolLib includes several in-game and console commands for debugging packet issues: /protocol is the base command, with subcommands for listing listeners, checking timings, and dumping diagnostic data. These tools are essential for server administrators troubleshooting performance problems or plugin conflicts.

The two most useful commands are /protocol listeners and /protocol timings. The listeners command shows every registered packet listener grouped by packet type, including which plugin owns each listener and what priority it runs at. The timings command measures how long each listener takes to process packets, helping you identify performance bottlenecks. On a server running 10+ ProtocolLib-dependent plugins, these commands save hours of manual debugging.

• /protocol listeners — Lists all registered packet listeners by type and priority
• /protocol timings — Shows processing time for each packet listener
• /protocol dump — Dumps full diagnostic info to a file for bug reports
• /protocol version — Shows the current ProtocolLib version
• /version ProtocolLib — Standard Bukkit command showing version and author info

Pro tip: If a player reports lag or rubber-banding, run /protocol timings immediately. Look for any listener with processing times above 1ms — those are your performance culprits. Packet listeners should complete in microseconds, not milliseconds. If a listener is slow, the responsible plugin needs optimization or should move heavy work to an async thread.

Explore all of ProtocolLib’s capabilities in our features section.

Stop the server, delete ProtocolLib.jar from the plugins/ folder, and optionally delete the plugins/ProtocolLib/ data folder. That is the entire uninstall process. There are no registry entries, no system files, and no leftover processes to clean up.

Before uninstalling, check which of your other plugins depend on ProtocolLib. Run /protocol dump or check each plugin’s documentation page. Removing ProtocolLib while other plugins still require it will cause those plugins to fail on the next server start. Common plugins that depend on ProtocolLib include Citizens, LibsDisguises, HolographicDisplays, TAB, and many anti-cheat solutions.

1. Run /protocol listeners to see which plugins currently use ProtocolLib
2. Remove or replace those dependent plugins first, or confirm you no longer need them
3. Stop the server fully (do not just /stop — wait for the process to exit)
4. Delete plugins/ProtocolLib.jar
5. Optionally delete plugins/ProtocolLib/ (the config/data folder)
6. Start the server and confirm no errors related to missing ProtocolLib dependency

Pro tip: Before deleting, move ProtocolLib.jar to a backup folder outside of plugins/ instead of deleting it permanently. If you discover a plugin you forgot about needs it, you can restore it in seconds rather than re-downloading.

Need to reinstall later? Visit our download section for the latest version.