Raspberry Pi Minecraft Server

by Gus

Updated Apr 16, 2024

A Raspberry Pi Minecraft server is a cost-effective way to have your very own private server with your friends or just for stuffing around on.

I have had mine running for quite some time now and haven’t come across too many problems. It is very important to know that this server will not be able to hold many people.

From my experience, anything over five people and the server will start to get a bit wonky. I found the optimal amount of people is only two to three, but this can be improved upon by tweaking the server.

We are also going to be using the spigot version of Minecraft as the default install didn’t work for me. I found that it will crash a lot, be laggy, and is very unstable. The official Java version may improve over time.

If you are looking for the Bedrock server, be sure to check out our Minecraft Bedrock server tutorial. It will take you through all the steps to setting it up correctly.

In this project, we will utilize Java, which should already be installed on Raspberry Pi OS. We will make a few changes to optimize the server for the Raspberry Pi 2, 3, 4, or 5. We will also set it up so you can access it on the web, and have it reboot if the Pi goes offline for any reason.

Equipment

Please find the equipment that I used for making this Raspberry Pi Minecraft server below.

Optional

Video Tutorial

If you want to see how to setup the server, then check out my video below. Otherwise, I have a detailed text explanation immediately below the video.

If you like the video, please make sure you subscribe or follow us on social, so you’re kept up to date.

Setting up the Raspberry Pi Minecraft Server

Firstly, we will need to install an operating system onto the Raspberry Pi. If you haven’t already done this, then check out my awesome guide on installing Raspberry Pi OS. It will take you through all the steps that you will need to do.

Important: You will need to be on the latest versions of Raspberry Pi OS. If not, then you will find that Java is not installed, this will need to be done if you wish to get this server working. I highly recommend updating to Jessie, Stretch, or Buster.

In this tutorial, we will work entirely in the terminal. It is probably best we boot straight into the terminal so we can save on memory by not loading the GUI.

1. First, let’s bring Raspbian up to the latest version by entering the following.

sudo apt update
sudo apt upgrade

2. Now we will need to make a couple of changes in the config tool. Let’s bring the tool up by entering the following line.

sudo raspi-config

If you need more information regarding the raspi-config tool check out our guide.

3. First, let’s go to Advanced Options->Memory Split, update this to 16. This will allow for more memory to be free for the server.

4. Also, you don’t want to boot into the Raspbian desktop, so ensure the boot option is set to the CLI (Command Line Interface) instead. This change will help give the server as much processing power as possible.

5. If possible, change overclocking to High.

6. Finally, also enable SSH so we can access the Pi remotely if required (Unless you already have it enabled).

7. Now go to finish and reboot.

8. We will now want the IP address of our Pi for when we try to connect to our server. To get the Raspberry Pi IP address, enter the hostname command.

sudo hostname -I

To ensure that the IP doesn’t change you might want to setup a static IP address.

8. Next, we need to make sure that Java and Git is installed. Otherwise, we will not be able to build or launch the server.

Enter the following command to install the JDK 17 package for Raspbian as well as the Git software.

sudo apt install openjdk-17-jdk git

9. Now we will need the Minecraft server file, and we’re going to use a builder tool that is supplied by Spigot, to get this enter the following commands.

mkdir /home/pi/minecraft
cd /home/pi/minecraft
wget https://hub.spigotmc.org/jenkins/job/BuildTools/lastSuccessfulBuild/artifact/target/BuildTools.jar

10. Now we will want to run the build tools file, so it creates our Spigot server. It will take about 15-30 minutes to finish.

Add --rev 1.20.4 to the end of the command to get the latest version. Don’t forget to change 1.20.4 in the command to the latest version number.

java -Xmx1024M -jar BuildTools.jar

Important: If you have a Raspberry Pi B+, B or any variation before the Raspberry Pi 2, then the build tools will likely fail. You will need to instead generate the spigot.jar on a more powerful computer.

11. To make sure the Spigot server successfully downloaded and saved simply type ls and should see spigot-1.20.4.jar (This may vary depending on the latest version available).

ls

Make sure you remain in the /home/pi/minecraft folder as we want all the server files to be created in here. If you start the server in a different folder, it will create the files in there.

12. Now we’re ready to launch the server, to do this enter the following command. (You may need to change the version number depending on what version you’re using e.g. spigot-1.20.4.jar)

Raspberry Pi 1

java -Xms256M -Xmx496M -jar /home/pi/minecraft/spigot-1.20.4.jar nogui

Raspberry Pi 2, 3, 4, or 5

java -Xms512M -Xmx1008M -jar /home/pi/minecraft/spigot-1.20.4.jar nogui

With the 2GB and 4GB variants of the Raspberry Pi 4 or 5, you can increase the Xmx value even higher.

The server will stop straight away as we will need to agree to the Eula. You can do this by opening the Eula by typing the following command.

nano eula.txt

13. In here, change false to TRUE, once done save and exit by pressing CTRL + X then Y.

14. Now relaunch the server, it will take a while to create a map so give it about three to five minutes. If you ever reboot again, it will only take thirty seconds to load if the map has already been created.

15. The server should now be running and accessible over the local network.

16. You might want to mod your user now so that you can use all the server commands when you log in. If we have it auto-boot on startup, accessing the server backend is slightly more difficult.

To mod your user, simply run the following command when the server has launched (Replacing username with your username).

op username

17. The Minecraft server on the Raspberry Pi will now be up and running fine, but you may want to do some optimizations to the server to make it run even better.

Connecting to the Minecraft Server

If you’re on a local network, then it should be pretty easy to connect to the Minecraft server running on the Raspberry Pi. To test it out, do the following steps.

Load up the Minecraft Java client on a computer within the same local network as the Pi.

Go to multiplayer, and your server might pop up in the local list. If it doesn’t, simply go to direct connect and enter the IP address we got earlier on the Pi using the hostname command, for example, hostname -I.

If you want to allow access to the Minecraft server via the internet, then you will need to setup port forwarding.

Assuming you want to learn how to do this, then head over to my guide on setting up Raspberry Pi port forwarding. You will need to port forward the port 25565 (unless you change it in the server properties) to the IP of your Pi.

Configuring the Server

Here are a few tips for configuring the server and getting it up and running.

Optimizing the Minecraft Server

To get the most out of our Minecraft server on the Raspberry Pi, you can install a plugin to help optimize the performance.

There are many plugins that can help with performance or extend the server’s functionality. Simply use the wget command to download them to the Pi. Below is an example.

cd /home/pi/minecraft/plugins
wget -O example.jar <example_plugin_url>

Editing the Minecraft Properties

You will probably want to know how to edit the server properties. This ability to edit is very important for optimizing the server and customizing it to how you want the server to be.

If you want more information for each of the server settings, you can find a good page on all the server properties here.

To enter the server properties, enter the following line.

sudo nano /home/pi/minecraft/server.properties

Now in here, we will want to change a few settings to help optimize the performance of the server.

You change these and other settings to whatever you like however you want, but keep in mind the Pi can’t handle too much processing.

view-distance=04
max-player=5

Boot on Startup

To have the server start on boot, we will need to do a few extra steps.

1. We will need to create a service for the Minecraft server so let’s start writing the service file by entering the command below.

sudo nano /lib/systemd/system/minecraftserver.service

2. In this file you will need to enter the following text.

This file defines the service, so the service manager knows how and what to run. Don’t forget to update the spigot version number whenever you upgrade.

[Unit]
Description=Minecraft Spigot Server

[Service]
User=pi
Group=pi
Restart=on-abort
WorkingDirectory=/home/pi/minecraft/
ExecStart=/usr/bin/java -Xms512M -Xmx1008M -jar /home/pi/minecraft/spigot-1.20.4.jar nogui

[Install]
WantedBy=multi-user.target

Once done, save the file by pressing CTRL + X then Y followed by ENTER.

3. Now, we will need to enable the service. You can enable the service by running the command below.

sudo systemctl enable minecraftserver.service

4. You should now be able to start the Minecraft server by simply using the following command.

sudo systemctl start minecraftserver.service

5. Using a similar command, you can check on the status of the service. Checking the status is great for debugging.

sudo systemctl status minecraftserver.service

5. You can stop the server by using the following command.

sudo systemctl stop minecraftserver.service

Your server should now start on boot. You can test it by restarting the Raspberry Pi. It will take a few minutes to startup.

If you want to get access to the server on the command line, then you will need to shutdown the server and load it using the normal command.

Conclusion

I hope this tutorial has helped you in setting up a stable version of a Raspberry Pi Minecraft server. If you like this tutorial, then be sure to check out our many other Raspberry Pi Projects.

Also, feel free to drop us a comment below if you have better optimization settings, plugins, or ideas. If you’re having trouble, let us know below.

294 Comments

Diana on December 29, 2017 at 11:13 am

I used this guide a while ago and it worked really well, but for chirstmas my mom finally got Minecraft. She set up a single player world and made a lot of progress, but wants me to join. Is there any way to take single-player save data and have my server run that? The goal is to pick up where she left off in the pi server, not just use the seed. Thank you!

Reply
1. Gus on December 29, 2017 at 12:19 pm
  
  Editor
  
  Hey Diana,
  
  Here are some steps to get to the folder that contains the world data that you are after.
  
  1. Firstly open up the Minecraft Launcher on your computer.
  2. Launch the latest version of Minecraft.
  3. Press the “Options” button.
  4. In the bottom left press the “Resource Packs” button.
  5. Press “Open resource pack folder”
  6. A folder should open. Go up one folder, if you are on windows pressing ALT + Up arrow key, should do the trick.
  7. This is the “.minecraft” folder
  8. Open the “saves” folder.
  9. Here are all your Minecraft world folders, you can then get her to zip that folder up and send it over to you.
  
  Hopefully that helps you get your Raspberry Pi Minecraft server up and running with her world data.
  
  Cheers
2. Diana on January 16, 2018 at 4:35 am
  
  Thank you, Gus! But I guess I was not clear-cut I don’t know how to put the current save data into the pi server. I had no problem finding it, thanks to your instruction, but I don’t know how to run it on the pi. Using FileZilla I found the location the original pi server world was in, but since new save data is not labeled “world/world nether/world the end” the way a world is when you make it on the pi server, I don’t know if a simple drag-and-drop would work.
3. Gus on January 16, 2018 at 3:15 pm
  
  Editor
  
  Hi Diana,
  
  Do you mind showing us the structure of new save data? As far as I know they should be cross compatible.
  
  Cheers
The Dirkness on December 26, 2017 at 5:02 am

Hi,

Can someone please leave a step by step tutorial how to update java, (if necessary) buildtools and spigot after this general tutorial, please? I try to this myself somehow, but I’m neither Linux user nor nerdy enough to fix this problem myself, but installed the MC server on my son’s RPI and he asks me every couple of months if there’s anything new on MC and if it’s already implemented on the server version.

Next is: I will move with the server within the next couple of weeks to an Mini ATX PC I want to run on linux. How to get the world from the RPI server moved to the ATX, what should I have to take care of about the ATX in general for a MC server base?

Lots of questions, I know. Sorry.

Reply
1. Gus on December 29, 2017 at 2:26 am
  
  Editor
  
  Hey The Dirkness,
  
  Running sudo apt-get update and sudo apt-get upgrade on Raspbian will ensure that you are running the latest version of Java on your Raspberry Pi.
  Updating Spigot should be simple as running through Step 9 and Step 10 of this tutorial again. You should rename the existing file to something else to keep it as a backup just in case.
  
  If you intend on moving your Minecraft server across the main files you will want to ensure is copied over is the “world” folder as that contains the player data and the world block data.
  
  Cheers
Matt on October 24, 2017 at 6:37 am

Hello,
How could I change the map to a pre-made one for the server?

Reply
Charlie Kosh on September 9, 2017 at 10:02 pm

Hey, first of all can I just say I love all the tutorials and all the lines of code to copy and paste incredibly helpful. I was wondering how to run the server with my own custom map?

Reply
1. IronBit on November 13, 2017 at 11:19 am
  
  Hi! You will find a “World” folder. Sometimes it is in /home/pi, or /home/minecraft. Replace the files in “World” with the files of the map that you would like to put onto your server. Just make sure to keep the name the same!
Bob Hilt on September 5, 2017 at 4:21 pm

I am stuck on running Buildtools.jar. Keep getting out of memory error (heap space), e.g., Exception in thread “main”

java.lang.OutOfMemoryError: Java heap space at org.objectweb.asm.tree.MethodNode.visitFrame(MethodNode.java:416)

Googling helped me increase the heap size as much as I could (before getting an invalid parameter error). I ran the command:

sudo java -Xms500m -Xmx2900m -jar BuildTools.jar

I’m running on a model B with 16GB SD card. How can I get past this memory issue? Is anyone successfully running on a model B?

TIA.

Reply
Dlanor on August 31, 2017 at 9:38 pm

Followed the instructions, no errors what-so-ever. Server is starting, without warnings / errors, but i cannot connect to it from my iPhone (where minecraft is installed).

It seems i cannot reach port 25565. Any suggestions?

Reply
Louise on August 30, 2017 at 9:13 pm

Thank you for this tutorial!

I have some problems with step 10. After using the following command “sudo java -jar BuildTools.jar” I get a lot of messages and the last message I get is “Final mapped jar: work/mapped.1ea8a6ae.jar does not exist, creating!” and it seems to be stuck at this point.

Does someone know how to fix this problem?

Reply
1. Louise on August 31, 2017 at 2:33 am
  
  Problem might be solved.
  
  After waiting for a few hours it is not stuck anymore.
King on July 14, 2017 at 3:50 pm

This is an amazing way to use your raspbery pi.
Worked, all good, no problems.
Nice job dude:)

Reply
Stuart on July 13, 2017 at 11:08 am

Hi Gus, thanks for the awesome tutorial. I’ve had a server up and running for a couple of months now with no problems. I was wondering how I can upgrade the mc version to 1.12 without overwriting my existing world? Is that possible?

Thanks in advance for any suggestions.

Reply
Alex on July 11, 2017 at 8:00 am

Hi so my pi is outputting an error when i attempt to start the server

Exception in thread “main” java.lang.UnsupportedClassVersionError: org/bukkit/craftbukkit/Main : Unsupported major.minor version 52.0

and i’m attempting to start it from a .sh file and the contents of that is
sudo java -Xms256M -Xmx496M -jar spigot.jar nogui

i’m on a raspberry pi zero running jessie lite with pixel installed. help is very appreciated

Reply
1. Gus on July 18, 2017 at 2:45 am
  
  Editor
  
  Sounds like an issue with java, have you tried running sudo apt-get update and then sudo apt-get upgrade
2. Alex on July 19, 2017 at 10:06 am
  
  Sorry i meant to comment earlier; i figured it out and it turns out that installing java8 did not update the default java path from openjdk7 to oraclejava8.
Tom on June 8, 2017 at 10:39 pm

When I try Step 9, it ends with a message saying ERROR 503: service unavailable, how do I avoid this problem, It also doesn’t allow further steps to be completed.

Reply
1. Gus on June 8, 2017 at 11:02 pm
  
  Editor
  
  It appears java.net is no longer available, I have removed these steps. You should be able to continue the tutorial unless you’re on Raspbian Wheezy, if so I highly recommend updating to Jessie.
Dennis on June 5, 2017 at 3:00 am

I am running a raspberry pi 3, and it appears the server is running, but, when i try to connect to it with a minecraft client i get

“Failed to connect to server”
“Outdated server, I’m still on 1.9”

Back to server list

how do i update the spigot to match my client version, and how to tell what version my client is running?

Reply
1. Dennis on June 5, 2017 at 3:34 am
  
  Now i get
  
  java.net.ConnectException: Connection refused: No further information
2. Gus on June 8, 2017 at 7:46 pm
  
  Editor
  
  Run the build tools with the following line to get the latest: java -jar BuildTools.jar --rev 1.12
  
  or you can download the latest build here: https://pimylifeup.com/out/spigotlatestbuild
  
  Are you still getting connection refused, I tested the latest and it appears to be working fine on my copy.
3. dennis on June 10, 2017 at 10:24 am
  
  io.netty.channel.abstractchannel$annotatedconnectexception: Connection refused: no further information
  
  i get this now
Joseph on May 10, 2017 at 1:21 am

Thank You So Much Gus, This server tutorial was by far the easiest thing to do.

I only have one problem-I can’t download the add-on, nospawnchunks, or any other add-on. I used the code you used, but it gives me an error 404-not found

If you could help me on this, I would really appreciate it

~Thanks!

Reply
1. Gus on May 10, 2017 at 9:20 pm
  
  Editor
  
  Hi Joseph,
  
  I have fixed the 404 issue, should be able to download it again. The download URL is different now so make sure you copy and paste the new command.
James on May 1, 2017 at 7:18 am

How do I add people to the whitelist?

Reply
James M on April 29, 2017 at 7:28 pm

Hi Gus,

I noticed if I unplug power from my Pi the world doesn’t save. If I attach a USB or hard drive to it will it save my world?

Reply
Liam on April 5, 2017 at 7:26 am

Is there any command i can run to update the whole server to the latest without losing data?

Understand if this isn’t possible.

Thanks

Reply
Daniel on March 23, 2017 at 10:26 am

Hello everyone. If you don’t want to port forward then I recommend you guys try ngrok you can use it on the pi by downloading linux version enjoy and good luck trying to fix it.

Reply
Chris on March 11, 2017 at 3:36 pm

Hey Gus,

My son and I did the 1.9 install, but MC is up to 1.11.2 now and it won’t connect to the server. How do we go about updating the server from 1.9 to 1.11.2.

Thanks! This has been a lot of fun.

Reply
1. Gus on March 11, 2017 at 4:22 pm
  
  Editor
  
  Hi Chris,
  
  The upgrade process is as followed.
  
  1) Stop/Shutdown the server.
  
  2) Backup the server folder, something like this should do the trick.
  
  sudo tar -cpvzf /home/minecraft.tar.gz /home/minecraft/
  
  It will add everything within the minecraft into a tar file that you can untar later if required.
  
  3) You can now run the build tools with 1.11.2 as a parameter. eg.
  
  sudo java -jar BuildTools.jar --rev 1.11.2
  
  Alternatively you can also find the latest version for download at: https://pimylifeup.com/out/spigotlatestbuild
  
  4) Once you have downloaded the new version, simply run the new server file and it should now be running on the latest version. You might want to double check any extra scripts you have to ensure they point to the new server file.
2. Chris on March 14, 2017 at 12:18 am
  
  Thank you, Gus. We had trouble with errors trying to upgrade the server so we just blew it away and did a fresh install with the new version. I sat back and let my son fight it out from loading Raspbian on the SD card to installing the server , forcing him to learn a ton in the process. The look on his face when I was able to connect to the server the first time was PRICELESS!! He’s 13 and I’m trying to gently push him into IT. Hopefully this will help. Thanks again for all you do.
Daniel K on March 8, 2017 at 4:43 pm

Ok so i get the java installed then i got the build tools and i don’t know what command I use to run the build tools. i tried your way and this is what it said: pi@raspberrypi:/home/minecraft $ sudo java -jar BuildTools.jar

sudo: java: command not found

what do i do.

I am using a raspberry pi 3 model B.

please help

Reply
1. Gus on March 9, 2017 at 12:54 am
  
  Editor
  
  If you installed java manually you will need to place /opt/jdk1.8.8_60/bin/ before java in the command for it to work correctly. Eg. sudo /opt/jdk1.8.8_60/bin/java -jar BuildTools.jar
  
  Hope that helps, let me know if you’re still having trouble.
2. Daniel K on March 9, 2017 at 6:15 am
  
  Sooo it says the command is not found. Please help.
3. Daniel K on March 9, 2017 at 1:49 pm
  
  This is what it says when i try the command:
  
  pi@raspberrypi:~ $ sudo /opt/jdk1.8.8_60/bin/java -jar BuildTools.jar
  
  sudo: /opt/jdk1.8.8_60/bin/java: command not found
Susana on February 6, 2017 at 3:27 am

I got a “java.io.FileNotFoundException” when launching the spigot server. If anybody else is having this problem, know that running it with sudo seemed to solve this issue.

Reply