How to Install Pufferfish on a Minecraft Server (Java, Startup Flags, and First-Run Setup)

To install Pufferfish, install a full Java runtime that matches your Minecraft version, download the matching Pufferfish server JAR, place it in a dedicated folder, and launch it from that folder with Java memory flags and --nogui. On the first run, review and accept the Minecraft EULA, then check server.properties, your firewall, and (if applicable) your router before inviting players.

Prefer not to run the server on your own PC? Godlike.Host offers hosted Minecraft Java servers with free DDoS protection and up to three free backups a day.

What Pufferfish is and what you need before installing

Pufferfish is a high-performance fork of Paper. Its project describes the goal as providing enterprise features and maximizing performance, while the GitHub project calls it a high-performance fork of Paper designed for large servers. Those are project descriptions, not independent benchmark results: the sources available for this guide do not establish a dated percentage improvement or a guaranteed player capacity.

#	Preview	Product	Price
1		Minecraft | Java & Bedrock Deluxe Collection | Windows Digital Code	$39.99	Buy on Amazon
2		Minecraft | Java & Bedrock Ultimate Collection | Windows Digital Code	$49.99	Buy on Amazon
3		Minecraft | Standard Edition | XBOX Digital Code	$19.99	Buy on Amazon
4		Minecraft	$6.99	Buy on Amazon
5		Minecraft - Bedrock Edition PS4	$42.98	Buy on Amazon

As an Amazon Associate I earn from qualifying purchases.

Because Pufferfish follows the Paper server model, Paper’s normal directory layout, command-line conventions, plugin model, and first-run workflow are the correct baseline. The Pufferfish project also states that plugins compatible with Paper are fully compatible with Pufferfish. A particular plugin can still have its own Minecraft-version or configuration requirements, so check the plugin author’s documentation when something does not load.

Checklist before you download anything

• Choose the Minecraft version you intend to run. The Pufferfish download page captured for this guide listed builds for 1.21.8, 1.20.4, 1.19.4, 1.18.2, and 1.17.1. The list changes, so confirm that the current download page has a build for your chosen version.
• Install a full Java runtime or JDK before launching the JAR. Avoid headless Java packages; Paper’s documentation warns that they can omit dependencies required by a server.
• Have a folder with enough free storage for the world, logs, plugins, backups, and future updates. Keep the server separate from your personal downloads and from unrelated worlds.
• Decide whether players will connect only from the same computer/LAN or from the internet. Internet access requires firewall and usually router configuration.
• Plan how much memory you can safely give Java. The example command uses 4 GB, but your value should reflect the host’s total RAM and the rest of its workload.

Choose the Java version for your Minecraft build

Java compatibility is tied to the Minecraft version, not to a single permanent Pufferfish requirement. Paper’s current compatibility table lists Java 21 for Minecraft 1.20 through 1.21.11, and Java 25 for Minecraft 26.1 and newer. If you select a different or newer version, re-check that table and the Pufferfish release notes before installing Java. Do not assume that the Java version used for one world will remain correct after a Minecraft upgrade.

#1 Best Overall

Minecraft | Java & Bedrock Deluxe Collection | Windows Digital Code

• DELUXE COLLECTION — Includes Minecraft: Java & Bedrock Edition, three Bedrock add-ons, three exclusive Character Creator items, and 700 Minecoins.
• CREATE YOUR WORLD — Build whatever you imagine in an infinite world that’s unique in every playthrough.
• EXPLORE AND CRAFT — Discover biomes, resources, and mobs, then craft your way through a sandbox world filled with surprises.
• SURVIVE THE ADVENTURE — Face mysterious foes, travel across exciting landscapes, and venture into perilous dimensions.
• PLAY TOGETHER — Play cross-platform with friends in Bedrock Edition on console, mobile, and PC, or join community servers in Java Edition on PC, Mac, and Linux. Online console multiplayer requires a platform-specific subscription (sold separately).

$39.99

Buy on Amazon

Install and verify Java

Use the operating system’s normal package or installer for a full OpenJDK distribution. Paper’s Linux example uses Amazon Corretto OpenJDK, while noting that other OpenJDK vendors exist; the important requirement is a supported, non-headless Java installation.

1. Install the Java major version required by your selected Minecraft/Pufferfish build.
2. Open a new terminal, Command Prompt, or PowerShell window so the updated PATH is loaded.
3. Run java -version.
4. Confirm that the reported major version is the one you selected. If the command is not found, Java is not on your PATH; if the wrong version appears, remove the ambiguity between multiple Java installations or invoke the correct Java executable by its full path.

Do this check before downloading or troubleshooting the server. A Pufferfish JAR that exits immediately with an unsupported-class or version message is commonly being launched with the wrong Java major version.

Download the matching Pufferfish JAR

Use Pufferfish’s official download page and select the build whose Minecraft version exactly matches the version you want clients to use. Do not mix a 1.21 build with a 1.20 world or expect a plugin compiled for one server version to work unchanged on another. The captured page listed 1.21.8, 1.20.4, 1.19.4, 1.18.2, and 1.17.1 builds, but availability can change as releases are published or retired.

Keep the server in its own directory

Create a new directory such as pufferfish-server. Put the downloaded JAR directly in that directory and open your terminal in the same location. Keeping the working directory consistent matters because the server creates world, logs, plugins, config, eula.txt, and other files relative to where the JAR is launched.

Do not rename the file unless you have a reason. The startup command must use the exact filename on disk. If you do rename it to something simple such as pufferfish.jar, use that new name consistently in every script and update procedure.

Start Pufferfish for the first time

From the server directory, launch the JAR with Java’s memory settings and the no-graphics option. Paper’s documented example is:

Rank #2

Minecraft | Java & Bedrock Ultimate Collection | Windows Digital Code

• ULTIMATE COLLECTION — Includes Minecraft: Java & Bedrock Edition, five Bedrock add-ons, five exclusive Character Creator items, and 1000 Minecoins.
• CREATE YOUR WORLD — Build whatever you imagine in an infinite world that’s unique in every playthrough.
• EXPLORE AND CRAFT — Discover biomes, resources, and mobs, then craft your way through a sandbox world filled with surprises.
• SURVIVE THE ADVENTURE — Face mysterious foes, travel across exciting landscapes, and venture into perilous dimensions.
• PLAY TOGETHER — Play cross-platform with friends in Bedrock Edition on console, mobile, and PC, or join community servers in Java Edition on PC, Mac, and Linux. Online console multiplayer requires a platform-specific subscription (sold separately).

$49.99

Buy on Amazon

java -Xms4G -Xmx4G -jar paper.jar --nogui

For Pufferfish, replace paper.jar with the actual Pufferfish filename. For example, if the downloaded file is named pufferfish-build.jar, the command becomes:

java -Xms4G -Xmx4G -jar pufferfish-build.jar --nogui

What each part of the command does

• java selects the Java runtime found on your PATH.
• -Xms4G sets the initial heap size to 4 GB in the example.
• -Xmx4G sets the maximum heap size to 4 GB in the example.
• -jar tells Java to execute a JAR file.
• The filename identifies the Pufferfish JAR. It must match exactly, including capitalization on case-sensitive systems.
• --nogui disables the graphical server window. The server continues to run in the terminal and accepts console commands there.

The 4 GB values are an example, not a universal recommendation. Set both values to the amount you can allocate without starving the operating system, desktop, backup process, or other services. Giving Java all available RAM can make the host unstable; giving it too little can cause slow chunk generation or out-of-memory failures. Change the numbers together unless you have a specific reason to use different initial and maximum heaps.

Run the command on each operating system

• Windows: open PowerShell or Command Prompt in the directory containing the JAR, then run the command. In File Explorer, you can navigate to the folder, use the address bar to open a terminal, and verify the filename with dir.
• Linux: use a shell, change into the directory with cd /path/to/pufferfish-server, and run the command. Verify the file name with ls.
• macOS: use Terminal, change into the directory with cd /path/to/pufferfish-server, and run the command. Verify the file name with ls.

On the first successful launch, Pufferfish creates the server’s initial files and begins the setup process. Keep the terminal open while it is running; closing it normally stops the server.

Complete the first-run EULA setup

Minecraft’s server software requires you to agree to the Minecraft EULA. Read the terms before accepting them. The first run normally creates eula.txt and stops or refuses to continue until the file records your decision.

1. Stop or return to the terminal after the initial launch reports the EULA requirement.
2. Open eula.txt in a text editor.
3. Read the linked EULA terms and, if you agree, change the setting from eula=false to eula=true.
4. Save the file without changing its name or extension.
5. Run the same Java command again.

Accepting the EULA does not configure networking, permissions, backups, or plugins. Those are separate administration tasks, and the server should remain private until you have checked them.

Configure the important server.properties settings

After the server has completed a start, stop it cleanly from the console and open server.properties. Paper documents defaults including server-port=25565, online-mode=true, and max-players=20. The file also controls server-ip, simulation distance, resource-pack behavior, and many other options.

Rank #3

Minecraft | Standard Edition | XBOX Digital Code

• CREATE YOUR WORLD — Build whatever you imagine in an infinite world that is unique in every playthrough.
• EXPLORE AND CRAFT — Discover biomes, resources, and mobs, then craft your way through a sandbox world full of surprises.
• SURVIVAL ADVENTURES — Face mysterious foes, travel across varied landscapes, and venture into perilous dimensions.
• PLAY TOGETHER — Play solo or join friends in local split-screen and cross-platform play across console, mobile, and PC. Online multiplayer supports up to 8 players.
• COMMUNITY PLAY — Connect with players on community servers, or subscribe to Realms Plus (sold separately) to play with up to 10 friends on a private server.

$19.99

Buy on Amazon

Save the file, restart Pufferfish with the same command, and watch the console for errors. Make one change at a time so you can identify which setting caused a problem.

Make the server reachable

Local or same-LAN connections

Players on the same machine can connect using the local host address and the configured port. Players on the same home or office network normally use the server computer’s private LAN address. Give them the address and port exactly as shown in your network configuration; do not expose the server to the internet merely to make a LAN connection work.

Internet connections

For players outside your network, the configured port must be reachable through two separate layers:

1. Allow the Java process or selected TCP port through the operating system firewall on the server host.
2. If the host is behind a router, forward the chosen external port to the server computer’s private address and the same internal port, or use the router’s equivalent rule.
3. Reserve the server computer’s private address in the router when possible, so a DHCP change does not break the forwarding rule.
4. Test from a network outside the host’s LAN. Testing only from inside the same network can produce misleading results because some routers do not support loopback connections.

Never publish your private LAN address as though it were a public address. Keep online-mode=true unless you fully understand the authentication and security consequences of another setting.

Install plugins and migrate an existing Paper server

The Pufferfish project states that it provides complete compatibility for plugins compatible with Paper. In practice, install plugins by placing their JAR files in the server’s plugins directory, then restart Pufferfish and review the startup log for load errors. Use plugin versions that support your exact Minecraft/Pufferfish version, and obtain them from their developers or established distribution channels.

Before migrating a Paper world, stop the old server cleanly and make a complete copy of the world directories, configuration files, and plugin data. Put the copy into the Pufferfish directory, preserve the existing world names referenced by server.properties, and start once with no new plugins if possible. This isolates a world-format or plugin issue from a migration issue. Do not downgrade a world or repeatedly switch between versions without backups.

Rank #4

Minecraft

• Skins! We have biome settlers, city folk, town folk, and more!
• The Nether and all its inhabitants. Fight Ghasts and make friends with Pigmen
• Cross platform play for up to five players between Pocket Edition and Windows 10
• Revamped touch controls, controller support, and a controller mapping screen
• Enhanced Weather effects! Accumulating snow and more

$6.99

Buy on Amazon

Keep Pufferfish updated safely

1. Record the current Pufferfish filename, Minecraft version, Java version, and installed plugins.
2. Stop the server cleanly and copy the entire server directory, including worlds, server.properties, eula.txt, plugin data, and logs, to a backup location.
3. Read the new Pufferfish build notes and confirm that it targets the same Minecraft version, unless you are deliberately performing a Minecraft upgrade.
4. Download the new JAR from the official Pufferfish download page. Keep the old JAR until the new build has started successfully.
5. Launch the new file with the same Java and memory command, then check the console for plugin or configuration warnings.
6. Have a rollback plan: stop the server, restore the backup or old JAR, and do not continue writing to a world with an incompatible build if the update fails.

A Minecraft-version upgrade is a larger change than replacing a build within the same version. Re-check Java compatibility, plugin support, world backups, and every configuration change before allowing players back in.

Troubleshoot common installation failures

“Java is not recognized” or “command not found”

Java is missing from the active PATH, or the terminal was opened before installation. Install a full supported runtime, open a new terminal, run java -version, and correct the system or user PATH. If multiple versions are installed, call the intended Java executable explicitly while you clean up the path.

Unsupported class-version or Java-version errors

The server was launched with a Java major version that does not match the selected Minecraft build. Compare java -version with the current Paper compatibility table for that Minecraft version. Install the required major version and ensure the startup script is using it, not an older copy.

“Unable to access jarfile”

The terminal is in the wrong directory or the filename in the command is wrong. List the directory contents, copy the exact Pufferfish filename, and run the command again. On case-sensitive systems, capitalization matters.

The server stops because of the EULA

Open eula.txt, read the terms, set eula=true only if you agree, save it, and restart. Editing a different copy of eula.txt will not help; the file must be in the directory from which you launch the JAR.

Players cannot connect

• Confirm that Pufferfish is still running and has finished starting.
• Confirm that the player is using the correct address and the port in server.properties.
• For LAN play, use the host’s private address; for internet play, use the public address and configure forwarding.
• Check the operating-system firewall and router rule.
• Confirm that server-ip is not set to an unavailable interface.
• Test from an external network if you are diagnosing public access.

Plugins do not load

Read the startup log for the plugin’s exact error, confirm that its JAR is in plugins, and check the plugin documentation for your Minecraft version. A Paper-compatible plugin is expected to be compatible according to the Pufferfish project, but that does not guarantee compatibility for every third-party plugin release or configuration.

Best Value

Minecraft - Bedrock Edition PS4

• Play and share with friends on console, mobile and Windows 10
• discover community creations in the new in-game store
• access new mini games and game modes through servers

$42.98

Buy on Amazon

The server runs out of memory or becomes unresponsive

Check the host’s total RAM and the values of -Xms and -Xmx. The example 4 GB heap is not mandatory. Reduce other workloads, choose a sensible heap for the machine, and inspect logs before repeatedly increasing memory. Simulation distance, plugins, world activity, and player behavior all affect load; no official source supplied a universal performance number.

Self-hosting versus managed hosting

Self-hosting gives you direct control over Java, files, ports, backups, and updates, but you are responsible for every one of those tasks. Managed Minecraft hosting can be a better fit when you do not want to maintain the Java installation, server directory, network exposure, backups, or upgrade process. Ask a provider specifically whether it supports the Pufferfish build and Minecraft version you need, whether you can upload plugins and world backups, how console access works, and how data can be exported.

The Pufferfish GitHub project says that Pufferfish Host provides hosting and tailored performance support to customers. That is a project statement, not an independent performance test or a guarantee for every plan. Whichever route you choose, retain your own world backup and confirm the provider’s supported Java and Minecraft versions before migrating.

Pufferfish and Paper: what the available evidence supports

Choose Pufferfish when its supported build and project-specific features match your needs, not because of an unsupported promise of a particular percentage gain. Measure your own workload if performance is the deciding factor: the relevant variables include Minecraft version, world, view and simulation settings, plugins, hardware, and player behavior.

Final pre-launch checklist

• The Pufferfish build matches the Minecraft version clients will use.
• java -version reports a supported full Java runtime for that version.
• The JAR is in a dedicated directory, and your startup command uses its exact filename.
• -Xms and -Xmx are appropriate for the host’s available memory.
• You have read and accepted the EULA before setting eula=true.
• server-port, online-mode, max-players, and other intended settings are reviewed.
• The firewall and router expose only the port you intend to expose.
• You have tested a local or LAN connection and, if needed, an external connection.
• Worlds, configuration, and plugin data have a restorable backup.
• Plugin versions are compatible with the selected Minecraft/Pufferfish build.

The Bottom Line

Install the Java version required by your Minecraft release, launch the matching Pufferfish JAR from a dedicated directory with an appropriate heap and --nogui, complete the EULA step, then verify server properties and network access before sharing the address.

Quick Recap

Bestseller No. 1

Minecraft | Java & Bedrock Deluxe Collection | Windows Digital Code

$39.99

Bestseller No. 2

Minecraft | Java & Bedrock Ultimate Collection | Windows Digital Code

$49.99

Bestseller No. 3

Minecraft | Standard Edition | XBOX Digital Code

$19.99

Bestseller No. 4

Minecraft

Skins! We have biome settlers, city folk, town folk, and more!; The Nether and all its inhabitants. Fight Ghasts and make friends with Pigmen

$6.99

Bestseller No. 5

Minecraft - Bedrock Edition PS4

Play and share with friends on console, mobile and Windows 10; discover community creations in the new in-game store

$42.98

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.