install minecraft server raspberry pi

Minecraft Server on Raspberry Pi: The Only Guide You Need

Minecraft is probably the game I’ve played the most, as a player and server owner (10+ years running a popular French server). As soon as I got my first Raspberry Pi, I tried to install a server on it. Now that I’ve mastered the process, I will share my secrets with you in this article.

While it’s possible to install the official Minecraft server on Raspberry Pi, it’s recommended to use Spigot instead, or even better: PaperMC. It’s easier to install, better optimized and allows the use of plugins.

I will start with some theory about Minecraft to make sure you understand what I’m talking about. But if this isn’t your first time, feel free to use the table of contents below to skip parts that are obvious to you.

If you’re looking to quickly progress on Raspberry Pi, you can check out my e-book here. It’s a 30-day challenge where you learn one new thing every day until you become a Raspberry Pi expert. The first third of the book teaches you the basics, but the following chapters include projects you can try on your own.

Minecraft vocabulary you need to know

What is Minecraft?

Minecraft is a sandbox game, created by Mojan, that has been available since 2011. This game has no defined goal. Each player will progress in the game in their own way.

When starting a new game, the player appears in a world composed of blocks, representing the real world in a cubic form. The player will find different biomes (meadow, beach, mountains) and various blocks such as stone, trees, water, etc.

Here is what it looks like by default:

play minecraft

The player must then gather resources to craft items and improve their stuff (tools, weapons, armor). In survival mode, monsters appear in caves and at night, so players must also fight for their survival along the way.

It’s an ideal game for kids that is very educational and not violent (you can disable monsters for the younger ones if you want). It is possible to play alone or with other players.

The purpose of this article is to show you how to set up a multiplayer game, with your family or friends.

Minecraft client and server

To play a multiplayer game, you will need two things:

  • A client: the game itself, installed on each player’s computer.
    It can be downloaded from the official Minecraft website. It’s available for all operating systems. It’s even possible to install Minecraft on a Raspberry Pi directly.

    Once installed, the launcher allows you to start a game, in single-player or multiplayer mode.
  • A server: That’s the part we’ll be talking about in this tutorial.
    Mojang provides a server on their website, but I don’t recommend it. The official server is very limited, it’s a single-player game where you’re allowed to play in cooperation, nothing more. But Minecraft servers can go way beyond that, with options to customize your server, add features, etc. That’s why we’ll use something else for the server.

Related: How To Install Minecraft Forge On Linux? (Illustrated Guide)

Minecraft server vs Spigot vs PaperMC

Now that I have introduced the basics, here is something important to understand.

You have 3 main ways to run a Minecraft server (on a Raspberry Pi or any system):

  • The official Minecraft server: very limited features and configuration options.
    This isn’t the best way, especially for a Raspberry Pi, so let’s skip this one.
  • Spigot: a custom version of the official Minecraft server that allows more configuration options, and more importantly, the possibility to use plugins.
    See plugins as add-ons to change the game experience.
    Want to add in-game commands? permissions? create an economy to sell items? There are plugins for that.
  • PaperMC: it’s the same thing as Spigot, with almost the same configuration files, and you can use the same plugins on it. It’s a bit faster to install, and overall more optimized for performance.

While on a powerful Linux server, using Spigot is fine (I explain how to install it on Debian here). I highly recommend PaperMC for a Raspberry Pi, as you’ll get better performance, especially if you are not using the latest Raspberry Pi model.

The installation is also a bit more straightforward, so why not?

Install a Minecraft server on Raspberry Pi

Here are the main steps to get a Minecraft server running on a Raspberry Pi:

  • Install the operating system and requirements (RPI OS Lite recommended).
  • Download PaperMC and create the folder’s tree for your server.
  • Start the Minecraft server.

Let’s learn how to do this step-by-step.

Operating system and requirements

It’s recommended to use a minimal operating system to host a Minecraft server. A GUI is not required, and the server is quite resource-hungry. So you can optimize the performance of the server by not running a desktop environment on it. Raspberry Pi OS Lite is perfect for this.

The following instructions will be the same with Ubuntu Server or other distributions but just know that I’m testing this on Raspberry Pi OS Lite (Bookworm). If you need help setting up Raspberry Pi OS, click on the link to read my step-by-step guide.

In terms of hardware, try to get the best setup you can. As I said, a Minecraft server will use plenty of CPU resources, but also RAM if you have several players on it or additional plugins. I’m testing this on my Raspberry Pi 5 with this SSD (links to Amazon).

If you aren’t getting the result you expect (lags and rollbacks), try to upgrade your setup.

You’ll also need the Java runtime installed on your Raspberry Pi. I added a link to my full tutorial about this, but you can also install it with these commands:
sudo apt update
sudo apt upgrade
sudo apt install default-jre

This will also update the whole system, so we don’t get any conflicts later on.

Download Your Essential Linux Commands Guide!
It's a free PDF guide containing every Raspberry Pi Linux command you should know!
Download now

Now that the system is ready, let’s move to the Minecraft server installation itself.

Are you a bit lost in the Linux command line? Check this article first for the most important commands to remember and a free downloadable cheat sheet so you can have the commands at your fingertips.

Downloading PaperMC

PaperMC is a pre-built Minecraft server, similar to Spigot in its uses. You can download the latest build from their website and run it directly on Raspberry Pi.

Here is how to download the main file:

  • On your computer, go to the Downloads page on PaperMC.
  • Copy the link to the latest build (right-click > copy link address).
  • Open an SSH session to the Raspberry Pi (or type the next command directly on the Raspberry Pi).
    If you need some guidance for SSH, read my tutorial here.
  • Then use this command syntax to download the file on the Raspberry Pi:
    wget <URL>
    For example:
    wget https://api.papermc.io/v2/projects/paper/versions/1.20.4/builds/381/downloads/paper-1.20.4-373.jar

This should download the file paper-<version>.jar in the current directory. That’s all you need at this point.

Create the Minecraft server file tree

Creating a folder dedicated to your Minecraft server installation is not required, but it is recommended.

This allows you to group everything in the same folder, know what files are associated with the server, and make things easier when setting up backups, for example.

Here is an example of how you can structure your files, but feel free to do whatever you want here:

mkdir /home/pat/minecraft
cp paper-1.20.4-373.jar /home/pat/minecraft/

Don’t forget to change the PaperMC filename to match the one you just downloaded.

Start the Minecraft Server

Now we can move to the server folder and start the server for the first time.

cd /home/pat/minecraft/
java -jar paper-1.20.4-373.jar

This start will fail, it’s normal. It will display something like this:

You have to first agree to the Minecraft EULA before running your server.

Your first start just created a file named “eula.txt” in the server folder.
Edit this file and set it to true:
nano eula.txt
Replace “false” with “true”.

Then start your server one more time.
The server will then complete the prerequisite steps before you can join the game:

  • Create the folder tree and all configuration files.
  • Generate the worlds for the three main dimensions (overworld, nether, end).
  • Start accepting connections on the default port.

This may take a few minutes depending on your setup.

When the server console displays “Done” you can stop it with this command:
stop
CTRL+C should also work, but it’s better to use “stop” to stop the server properly.

Technically, our server is already working. But we’ll first take a look at the available configuration before moving on to play Minecraft.

How to configure Spigot

We installed PaperMC, but that’s the same thing as Spigot once installed. I’ll use both terms interchangeably, and you can check resources for Spigot to apply them on your new server.

Spigot allows us to configure everything to create the perfect Minecraft server. We will see in detail what it is in each configuration file and what you can do with it.

First, you’ll notice that almost all configuration files are in YML format. This format is easy to read, but it’s important to respect the syntax, as it’s very strict. You can’t use tabs (use spaces instead) and any indentation mismatch can cause fatal errors, so be careful when editing these files.

Server.properties

The first file that can help you to configure the server’s basic settings is server.properties.
This file comes from the original server from Mojang, Spigot keeps it for more compatibility.

Open the file to see what’s in it:
nano server.properties

As you can see, the file is easy to read: one parameter = one value.

Now I will explain the most important options from this file, that you’ll probably use:

  • server-port: By default, the Spigot server can be accessed to port 25565, but you can change it with this parameter.
  • level-seed: Each world is generated from a seed. If you want a specific world, you can enter a seed here, delete the world folder and restart the server to get this exact world. There are a lot of websites giving you examples of seeds. MinecraftSeedHQ is one of them.
  • hardcore: Do you want to make the game more complicated? The hardcore mode will ban the players at their first respawn.
  • pvp: (Players vs Players) You can disable this option to avoid PVP on your server.
  • difficulty: By default, the server will be in EASY mode. You can increase this value to make it more difficult (values between 0 and 3).
  • gamemode: By default, the server will be in Survival mode. You can change this value to play in another game mode (0=Survival, 1=Creative, 2=Adventure, 3=Spectator).
  • spawn-monsters: You can disable this if you want to play without monsters.
  • motd: It’s the name of the server that will be displayed in your server list. You can change it to know that it’s your Raspberry Pi server.

You can find all the other options in the Minecraft wiki but most of the time you won’t need to change more than that.

Spigot.yml

Spigot.yml is the first configuration file added by Spigot to customize your Minecraft server.
It will allow you to change game settings and server settings.

For example, you can change the hopper’s speed or the log file behavior in this file.

Most of the time for a home server, you will not need this kind of option. You could probably spend a little time in this file to improve the performance of your Raspberry Pi, but it’s not mandatory.

If you want further information about this file, you can find it in the Spigot wiki.

Bukkit.yml

Spigot is based on Bukkit. Bukkit was a similar project, to extend the multi-player Minecraft server. Spigot decided to keep the bukkit.yml file that contained all the options for Bukkit servers.

This file contains pretty much the same kind of options as spigot.yml. It is also often complicated to know in which file we will find which option.

In the same way, as for the Spigot.yml file, it is unlikely that you need to go to edit bukkit.yml. However, if you want to know more, help is available on their wiki.

Paper.yml

Since you used PaperMC to install the server, you also have access to a bonus file: paper.yml. Like spigot.yml, it gives you access to more advanced configuration options.

These settings are particularly useful for optimizing performances. I recommend keeping the default, to see if it’s working properly, and only editing this file if your Raspberry Pi model can keep up with the server demand.

Connect to the server

Take your time to finish the server configuration, and we can continue to test the server access.

Download Your Essential Linux Commands Guide!
It's a free PDF guide containing every Raspberry Pi Linux command you should know!
Download now

Don’t forget to restart the Minecraft server with your new configuration files:
java -jar paper-<version>.jar

Get the game launcher

If you don’t have it yet, you need to download the launcher from the official website.
Log in to your account, and click the Download link.

Start the launcher

If you are using the official launcher, it will ask you to log in on the first start:

Enter your credentials and submit the form.
Then you will get the Play button:

But before clicking the play button, you need to check that the game will start with the same version as your server.

Most of the time when a new Minecraft version is available, the server developers will need some days/weeks to update the server, so there is often a gap between the two versions.

For example, if the server is in 1.20.4, but the launcher starts in 1.21, you need to change this first.
So, to change it:

  • Go to “Installations” in the menu.
  • Click on “New”.
  • Enter a friendly name (ex: 1.16.5).
  • Choose the same version as your server.
  • Click on “Create” to save these values.

If you come back to the launcher home, you now have access to your new installation via the left dropdown list:

Add the server

Whatever the chosen version, you should now find yourself on a screen like this:

If you have not done it yet, take a look at the game’s options to adjust controls, audio and graphics options to suit your needs.

Then we’ll add our server and connect to it:

  • Click on the Multiplayer button.
  • Click on the Add server button.
  • Enter a server name (whatever).
  • Enter your Raspberry Pi IP address:

    If you changed the default port, you have to put it in this field following the format [IP]:[PORT], for example, 192.168.1.200:12345.
  • Click on the Done button.
  • Your server should now be listed as an option to join the game:

Double-click on it to connect to your server!
If you check the server console, you’ll see your player name logged in.

We now have a basic functional server. You can already play with your family or friends.

But we chose Spigot to be able to add plugins, not to get a simple server. So, that’s what we’re going to see now.

Adding plugins to your Minecraft server

What are plugins?

As I said before, plugins can improve or change the behavior of Spigot.

I will give you some examples of features that plugins can bring.
It will be clearer:

  • Add commands, for example, the ability to return to the server spawn with the command “/spawn”.
  • Give you rewards based on what you do in the game.
  • Add permissions, such as not being able to break another player’s house.

There are thousands of plugins that are already full of things.
And the possibilities are almost endless, develop a new plugin to add any functionality that you have in mind.

Download plugins

Spigot lists most public plugins on its website, in the Resources category.
You can search for a plugin through the Categories menu or with the search engine.

Note: There are no specific plugins for PaperMC, you can use the same ones as with Spigot.

For a family server, you don’t need to add plugins. If you trust the people who access the server, the basic version may be enough. But if you want more security or more features, do not hesitate to add a few ones.

Here is a list of the main plugins found on the majority of multi-player servers:

  • Essentials: Essentials will add all the most useful commands to your server. For example, you can create checkpoints with /sethome and come back to this place with /home.
    I often install it, even if I’m the only player, as it’s very convenient.
  • LuckPerms: LuckPerms will add permissions to your server. Players will only be able to do what you have decided. You can create groups of players, like Admins with all access, and players with only the minimum permissions.
  • WorldGuard: WorldGuard will allow you to create protected regions in your world. For example, you can preserve the spawn of the server, to avoid its destruction by new players.
  • WorldEdit: WorldEdit works well with WorldGuard, it allows you to make the selection of a region, and transformation of the world (copy/paste for example).
  • Multiverse: Multiverse-core is a plugin to manage multiple worlds in your servers. For example, you can have a resource world and a build world.
  • Vault: Vault allows players to use money in the game.
  • Lockette: Lockette is a simple plugin to protect chests or doors. If you put a private sign on your chest, nobody can open it except you.

There are many others, which may be useful depending on what you want to do, but those are part of the essential plugins.

Plugins are java files in a .jar format.
To download one, go to the plugin page (ex: Multiverse), click Download and get the .jar file.

We’ll see next how to install them on your Spigot server.

Install plugins

To add new plugins on Spigot, you have to put the .jar file in the “plugins” subfolder.

Transfer it from your computer

If you have downloaded the plugin file on your computer, you have to transfer it via SSH to your Raspberry Pi:

  • On Mac/Linux: use scp or rsync command:
    scp Multiverse-Core-2.5.jar pat@192.168.1.22:/home/pat/minecraft/plugins/
    Don’t forget to change the IP address of the Raspberry Pi and the destination folder.
  • On Windows: use the WinSCP software or any alternative.
    • Create a new site with your Raspberry Pi settings.
    • Then click Save and Login.
    • The right tab is the Raspberry Pi folder tree.
      Go to /home/pat/minecraft/plugins
    • Drag and drop the plugin from the left to the right.

Direct download

Another way to do this is to download the file directly to the Raspberry Pi. This way is not always possible, but when you have the plugin’s direct link, you can use wget to download the file:
cd /home/pat/minecraft/plugins/
wget [LINK] -o [PLUGIN].jar

Apply changes

Whichever method you use, you now need to restart the server to apply the changes.

  • Return to the server console in your SSH client.
  • Stop the server:
    stop
  • Then restart the server:
    java -jar paper-<version>.jar

On the next start, the plugin will be installed and available in the game.

Configure plugins

Most of the time, when you install a new plugin, a new folder will be created in the “plugins” folder. This folder contains the plugin configuration.

├── Multiverse-Core
│   ├── config.yml
│   ├── scripts
│   │   └── scripts.bin
│   └── worlds.yml
├── Multiverse-Core-2.5.jar

If necessary, edit these files by referring to the documentation of each plugin.

Bonus tips for your Minecraft server

These tips are not mandatory to play Minecraft on your server.
But it can help you to have a more stable server.

Use screen

As you’ve probably noticed, the server you launch in your SSH console stops if you are disconnected from the Raspberry Pi or if your computer goes to sleep.

We have to start the Spigot server on the Raspberry Pi directly.
For that, I recommend you use screen:

  • Install screen:
    sudo apt-get install screen
  • Create a new screen for your Minecraft server:
    screen -S minecraft
  • Start the server:
    cd /home/pat/minecraft/
    java -jar paper-<version>.jar
  • Quit the screen with CTRL+A followed quickly by CTRL+D.

This time even if you disconnect your SSH session the server will continue to run.
To return to the screen, use the following command:
screen -r minecraft

More info: The ‘screen’ Command on Linux: A Beginner’s Guide.

Start server script

For now, we have started our server manually, but it is advisable to create a script for that.

A simple script

Here is the most basic script you can create to start your Minecraft server.

  • Go to your server directory:
    cd /home/pat/minecraft/
  • Use nano to create the script:
    nano start.sh
  • Paste these lines:
    #!/bin/bash
    java -jar paper-<version>.jar
  • Save and exit (CTRL+O, Enter, CTRL+X)
  • Add the execution permission:
    chmod +x start.sh
  • Start the server:
    ./start.sh

As you may notice in the spigot.yml configuration file, if the server crashes, Spigot will look for a start.sh script to restart the server, so it’s important to call this script exactly like this.

Options

Most of the time, we start servers with additional parameters.
Java can take many options, and Spigot too.

You may notice that in the server start, they recommend using another command, so we will edit out the script to add these options:

#!/bin/bash 
java -Xmx1024M -Xms1024M -jar paper-<version>.jar
  • -Xmx specifies the maximum size, in bytes, of the memory allocation pool.
  • -Xms specifies the initial size, in bytes, of the memory allocation pool.

Auto restart

The last thing we can add to this script is an auto-restart.
We saw that in case of a crash, Spigot would try to restart the server.
But it does not always work, and if you stop the server yourself accidentally, you have to go and restart it.

For the server to restart automatically, modify your startup script so that it looks like this:

#/bin/bash
while true
do
  java -Xmx1G -Xms1G -jar paper-<version>.jar
  echo Reboot
  #You can add other commands to do at each reboot here
  #(backup or log rotation for example)
  sleep 5
done

Start on boot

Finally, if your Raspberry Pi is dedicated to your Minecraft server, you can launch it automatically at every boot.

For that add the script in the crontab this way:

  • Edit the crontab:
    crontab -e
  • Paste this line at the end:
    @reboot /home/pat/minecraft/start.sh
  • Save and exit (CTRL + O, Enter, CTRL + X).

Backups

If you spend a lot of time playing, setting up a backup at least once a day can be a good idea.

For minimum security, you can install a backup plugin like this. This plugin will create backups at defined intervals and allow you to restore them easily.

For a more valuable server, it will probably be necessary to put in place a more advanced strategy. For example, you can create a compressed archive of the server folder, keeping a few days of archives. This article might be useful to do this.

You may even want to consider cloning the entire Raspberry Pi SD card from time to time to make sure you have a complete recovery point available if needed.

❤️ Love Raspberry Pi & writing?
Combine your passions and get paid. Write for RaspberryTips!

Access from Internet

As you have seen your Minecraft server is accessible via an IP and a port.
It is therefore quite possible to open this port on the Internet, by adding a NAT rule on your Internet box

This firewall rule will allow you to invite friends to play on your server. But in this case, think about the security of your server, adding the plugins recommended above because anyone can come on your server.

How to Install and Use No-IP on Raspberry Pi? (Dynamic DNS).

Download Your Essential Linux Commands Guide!
It's a free PDF guide containing every Raspberry Pi Linux command you should know!
Download now

Video

If you want to see a summary of all the first steps to install Minecraft Server on your Raspberry Pi, you can watch this video:

Download Your Essential Linux Commands Guide!
It's a free PDF guide containing every Raspberry Pi Linux command you should know!
Download now

🛠 This tutorial doesn't work anymore? Report the issue here, so that I can update it!

If you are looking for exclusive tutorials, I post a new course each month, available for premium members only. Join the community to get access to all of them right now!

Conclusion

You now know how to set up an advanced Minecraft server on a Raspberry Pi at home.

Minecraft is an infinite universe, whether in the game or its community, its plugins, and its improvement possibilities.

If you didn’t know it you shouldn’t be disappointed, and if you have already played solo, the discovery of the multiplayer mode should revolutionize your games.

Whenever you’re ready, here are other ways I can help you:

The RaspberryTips Community: If you want to hang out with me and other Raspberry Pi fans, you can join the community. I share exclusive tutorials and behind-the-scenes content there. Premium members can also visit the website without ads.

Master your Raspberry Pi in 30 days: If you are looking for the best tips to become an expert on Raspberry Pi, this book is for you. Learn useful Linux skills and practice multiple projects with step-by-step guides.

The Raspberry Pi Bootcamp: Understand everything about the Raspberry Pi, stop searching for help all the time, and finally enjoy completing your projects.

Master Python on Raspberry Pi: Create, understand, and improve any Python script for your Raspberry Pi. Learn the essentials step-by-step without losing time understanding useless concepts.

You can also find all my recommendations for tools and hardware on this page.

Similar Posts

12 Comments

  1. I dont know if anyone will read or respond to this but, after the nether spawn area is getting prepared when I boot up the server says exception: java.lang.OutOfMemoryError thrown from the UncaughtExceptionHandler in thread “Server console handler” im basically clueless on what to do, anything will help.

    (Sorry if this isnt what the comment section is for)

    1. You need to allocate more RAM to your server. To allow 1Gb, run [java -Xmx1G -Xms1G -jar spigot-1.14.2.jar]

  2. Thank you for that amazing and detailed tutorial. It works like a charm on my Raspberry 3+. That is, at least when running the client on my Mac. The problem is, I (and my son) also have a second Raspberry 4. I installed Minecraft 1.12.2 with this other amazing Tutorial:

    https://html.dynu.net/index.php/how-to-setup-minecraft-on-raspberry-pi-forge-version-1-12-2/

    It works fine in single player, but when I try to access the server, I get the following error message:

    Failed to connect to the server
    Internal Exception: java.lang.nullPointerException

    Both Raspberries run on Raspbian Buster and are pretty vanilla. They also have the same version of java:

    java -version
    openjdk version “1.8.0_212”
    OpenJDK Runtime Environment (build 1.8.0_212-8u212-b01-1+rpi1-b01)
    OpenJDK Client VM (build 25.212-b01, mixed mode)

    If anyone finds the time, help would be greatly appreciated. Especially by my son!

    Cheers,
    Fabian

    1. Thanks for your comment Fabian

      Can you check that it’s the same Minecraft version everywhere?
      So if the server is in 1.12.2, clients must also be in 1.12.2

      As the last version is 1.14, the client is probably not on 1.12 (by default, but you can change it)

      1. Dear Patrick,

        thanks for the hint, but that’s definitely not it. As far as I know, 1.12.2 is the highest version that can run on a pi-client anyways, and both have it.

  3. Hi there, Can we have a tutorial on how to make this accessible from the internet?
    Thanks

    1. Hi,

      It depends on your modem or router, so it’s difficult to write a tutorial about this
      Generally you’ll find something like “Port forwarding” or “NAT” in the interface (often in the Firewall part)

      Redirect an external port (the one you want) to your Raspberry Pi IP and Minecraft port
      So, for example, redirect port 8888 to 192.168.1.20:25565

      Then, ask your friends to connect to YOUR_PUBLIC_IP:EXTERNAL PORT
      You can use a service like No-IP if you don’t have a static public IP (https://www.noip.com/)

      If you need more information look for documentation for your specific router model

  4. So I was at step: Run Buildtools –> java -jar BuildTools.jar, and my Raspberry 4B 4GB (overclocked to 1.75 GHz with over_voltage=2) suddenly died. I have the Flirc Case and the Pi was at only 61°C. Do you have an Idea why?

  5. I’m having trouble taking the server down, it seems to want to perpetually reboot when I tell it to stop or use CTRL+C to force it to stop. I’ve tried editing the start.sh script and the crontab, can you offer me any other avenues I can try?

    1. Hello,

      Don’t do the start.sh script if you don’t want it to restart automatically
      Just run the command manually

      Patrick

  6. Hi !
    I don’t know if anyone will read this but I have to say first thank you very much for this wonderful tutorial it’s working perfectly well!
    I simply had a question concerning a password. I would like to add a password to my server. Anyone knows how to do this ?
    Thanks in advance !

Comments are closed.