The Minecraft world of color update 1.12 has finally arrived! This walk through will show you how to set up a playable Minecraft server running on the Raspberry Pi.
ATTENTION: New 1.16 guide is available! Many things in this guide have changed and no longer apply.
I have read many tutorials on Google about how to set up a “great performing” Minecraft server on your Raspberry Pi and have been sorely disappointed by the results. Most tutorials are very outdated and tell you to turn your view distance all the way down to 4 (meaning you can’t see very far), or turn your entities (monsters/animals) down to settings so low that they hardly spawn or you can walk right up next to them before you see you.
After much research, trial and error, and spending time in the #Paper IRC channel talking to the smartest people in the Minecraft server configuration world I have been able to get the Minecraft Server (popular Paper fork based on Spigot) to run at vanilla settings (view distance 10, no reduction in entity settings). This means the server is suitable for full survival mode just like a regular vanilla Minecraft server.
Should you try this?
Let me answer a big question right off the bat. Should you buy a Raspberry Pi just to run it as a Minecraft server? Absolutely not. If you just want to run a Minecraft server, especially one with more than a few people, you are much better off buying a realms subscription or one of the many dedicated Minecraft server options.
The price of the Pi would get you approximately 6 months of a Realms server and probably much more from private hosts. You may also be better off just running the server off your own computer because your CPU and RAM in a desktop class machine is almost certainly going to be better than a Pi. However, if you already have a Pi just laying around or want to use it to learn a bunch of cool new stuff like setting up a headless Linux server on an embedded device then by all means proceed. It’s a great setup to play Minecraft with a few friends.
Second question: Do you have fast Raspberry Pi storage? Because this tutorial will overclock your SD port from 50hz to 100hz. (Update: Since I wrote this article solid state storage has gone down so much in price that it makes much more sense!) If you have a good SanDisk A1 Class 10 card you should have no problems. However, although the risk is minimal, there is some risk of SD card corruption if you don’t have a high quality card. I am not responsible if your card dies,
your Pi explodes, your house gets hit by a meteorite, or anything else that happens! This is solely at your own risk! These are very common overclocks though and the risk is minimal, but you have been warned!
If you are prepared to continue, then read on!
- Raspberry Pi with 1GB of memory or higher required. The 1GB of memory in these boards is still barely enough to run the server and can only support a few people. The 4B 2GB and 4GB models have much more breathing room. If you are using a 512MB version of the Pi (like a Raspberry Pi Original Model B/B+ you are not going to get the performance necessary to deliver a stable Minecraft experience without major sacrifices that will be outside the scope of this guide.
- SSD or *Highly* ranked Micro SD card (SanDisk Extreme or other highly ranked card. Here are some benchmarks of SD cards on Raspberry Pi for comparison. It is extremely important you do not skimp on this as IO performance is the biggest bottleneck in the Raspberry Pi when running a Minecraft server)
- Latest Raspbian Lite image (currently Buster) https://www.raspberrypi.org/downloads/raspbian/ We need the Lite version because ALL of the Pi’s resources will need to be devoted to running the server. This is command line only and we cannot use an X environment because we need all available memory for the Minecraft server
- A highly rated power supply capable of providing more than enough of the power we need. Do not plug this into a USB hub unless you know it is powered and has more than enough power for the Raspberry Pi. You also need a good power cable. The official Raspberry Pi power supply or the Canakit power supply (linked below in my configuration) will suffice.
- Minecraft “Paper” Server
- Ethernet connection to your router. Wireless is *not recommended* for a dedicated server or any kind! Wireless adds so much overhead not to mention signal strength issues, interference with all nearby access points, etc. Unless you have absolutely no choice you should directly wire the PI to your router with an ethernet cable. If you have a Pi3 the wireless chip only supports wireless N and not wireless AC on the broader bandwidths. Even if you have a dongle that does support a wireless AC connection it will slow down your Pi by adding overhead to the USB bus which is an extremely limited resource on the Pi because the Pi basically shares that bus with everything else and we need those lanes as clear as possible.
These are the components used in my setup:
Windows Initial Setup Requirements:
- If you aren’t using Windows then you probably don’t need help with this part and can skip to the Raspbian Lite configuration section
- SSH client – This allows us to connect to our server via SSH. SSH is command line only. I recommend Putty which can be downloaded for free here https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html
- Win32DiskImager (writes our Raspbian Lite image to the SD card)
Getting Started – Imaging your SD card for use with the Raspberry Pi
Unzip the Raspbian Lite image you downloaded and use Win32DiskImager to write it to your SD card. Insert your Micro SD card into your computer’s Micro SD adapter slot. If your computer can already take MicroUSB cards without the adapter then just stick it right in there.
Now open Win32DiskImager and click the little blue folder icon on the Image line and browse to where you unzipped the Raspian image and select it. The image line should now be populated with your Raspbian.img file. You must now select the drive to write the image to. This will be D: or some other letter depending on how many drives you already have on your computer.
Win32DiskImager should hide most of the drives you shouldn’t pick like your C: drive but other drives might show up. Warning: Don’t screw this one up! Double, triple, and quadruple check that you select the CORRECT drive to write your SD image to. If you pick the wrong one it will overwrite that drive and you will be screwed!
The write process will take a few minutes but it won’t take too long because the Raspbian Lite distribution is much smaller than the full distribution. Once the write completes Win32DiskImager will tell you it is done. Okay, excellent, we have now formatted your MicroSD card with Raspbian Lite.
There is still one step we need to do. Raspbian Lite has no X based window manager and is console only. We need to configure the Pi for SSH access so we can get in with SSH. You can alternatively hook it up to a TV and plug a keyboard in, but since this article is about setting up a headless server I encourage you to do it using SSH.
You should now be able to browse to your SD card in Windows. Go to your SD cards base folder which will just be called “boot” and create an file called ssh with no file extension. Make sure that you do not make something like ssh.txt or anything. It will be just “ssh” with no file extension.
If you create the ssh file and it looks like a text/Notepad document for the icon then you have your file extensions turned off. Click “View” at the top of the window and you will see a checkbox under “Show/Hide” that says File Extensions. Check this box and you will see the ending extensions for every file. If there is no extension and you have a file that just says “ssh” then you are good to go. Have Windows safely eject the drive and let’s proceed. Put the newly formatted card into your Raspberry Pi and fire it up.
Initial Raspbian Lite Configuration
We need to get the newly assigned IP address to your Raspberry Pi. The easiest way to do this is to log into your routers configuration page and view your connected devices. If you do not know how to do this then you need to look up how to sign into your router’s configuration page because you will need to set up port forwarding later if you want anybody outside of your own network to be able to connect to the Minecraft server.
The default hostname is going to be something like rpi3 or raspberrypi. While you are configuring this I strongly suggest you assign a static IP address for your Raspberry Pi. This is so that when you set up port forwarding so other users can connect from outside your network that you won’t receive a new IP address the next time you restart your router which would make them unable to connect again. Now that you know your IP address it’s time to fire up Putty and make a SSH connection to your server. Put the IP address into Putty and leave the port to the default 22 and click open.
Now it’s time to log into the pi using the default username of pi and the password raspberry. Now that you have signed in and changed your password it’s time to configure Raspbian.
- Step 1: Type
sudo raspi-configand it will take you into the Raspberry Pi configuration options. Choose menu option #1 and Change your password immediately. The stock password of raspberry is the same for everyone and is a huge security risk. This is the very first option on the raspi-config page. Select it and choose a secure password.
- Step 2 (Optional): You may change your hostname with menu option 2 to whatever you want, such as minecraftserver. If you want to leave it as raspberrypi (the default) that is fine too.
- Step 3: Choose menu option 4 (Localization Options). By default all Raspbian images will be in the en_GB language. Choose option 1 to change locale and go down and uncheck en_GB and check your own locale’s UTF-8 option. This is important for performance later as the Minecraft server is formatted it UTF-8. For example, on my system I unchecked en_GB and checked en_US.UTF8. Press tab until you get to the Ok button and save these settings. It will now update your locale and ensure you are using UTF-8.
- Step 4: Choose your timezone. This is the second option in the localization options right under ‘Change Locale’. Select your time zone and hit Ok.
- Step 5: Interfacing options: Here we need to enable SSH. Even if you did option 2 earlier you still need to do this again or the next time you reboot you won’t be able to SSH in without pulling out the card and recreating that ssh file in the boot folder. Enable SSH and hit ok.
- Step 6: Choose “Advanced Options” from the main menu. Now choose “Expand Filesystem” which will expand your partition to the maximum size of your SD card so you can actually use all your space.
- Step 7: Under “Advanced Options” choose option 3 which is “Memory Split”. We are going to set your GPU memory to 16mb. GPU memory on the PI is actually taken out of your RAM so it goes to waste on a headless system. It does not go lower than 16mb so do not try. Choose 16mb and hit ok.
- Step 8: We are done in this configuration utility. Hit the tab key until “Finish” is highlighted and hit enter. Make sure that you don’t accidentally highlight the cancel option or you may have to do all these steps again. It will now ask if you want to reboot the system. Say yes as this is when many of the changes will take place such as expanding the filesystem which cannot be done without a reboot
After your Raspberry Pi reboots log back in with SSH. We now need to update the system. Type the following command to update the system:
sudo apt-get update && sudo apt-get upgrade
This may take some time based on the speed of your internet connection. After all of the updates have completed reboot your system by typing
Since we chose the lite image Java is not yet installed on the system, but we are *not* going to use the Java in the Raspbian Jessie repositories because it is outdated and many performance fixes and optimizations have been added. We are going to download the latest Oracle JDK ourselves. At the time of writing the latest Java JDK for hard float ARM (Raspbian 32bit) is jdk-8u131-linux-arm32-vfp-hflt.tar.gz.
Use the following commands:
wget --no-check-certificate --no-cookies --header "Cookie: oraclelicense=accept-securebackup-cookie" https://download.oracle.com/errors/download-fail-1505220.html
If the download was successful you may proceed to the next following commands which will extract the JDK. If it was not successful you need to go to the Oracle Java website and download the latest JDK manually. Once you have downloaded the JDK type the following commands to install it:
sudo mkdir /usr/java
sudo tar xf ~/jdk-8u131-linux-arm32-vfp-hflt.tar.gz
Okay, we have extracted Java, now we need to tell the system that it is installed and where to find it using update-alternatives. Use the following commands:
sudo update-alternatives --install /usr/bin/java java /usr/java/jdk1.8.0_131/bin/java 1000
sudo update-alternatives --install /usr/bin/javac javac /usr/java/jdk1.8.0_131/bin/javac 1000
Alright, that is it. Now lets test and make sure that Java is working properly.
If everything went correctly, you should see something like:
java version “1.8.0_131”
Java(TM) SE Runtime Environment (build 1.8.0_131-b11)
Java HotSpot(TM) Client VM (build 25.131-b11, mixed mode)
If you see this, then congratulations, you’ve installed the latest JDK and are now done with Java configuration for the system.
Minecraft Server Initial Setup
I have all the latest configuration files I am using to run the server uploaded to my GitHub. Lets replace the default versions with these ones to use as a starting point.
My GitHub repository is located at https://github.com/TheRemote/RaspberryPiMinecraft
Lets download this repository and make our folder to extract the files to. Type/paste the following:
unzip master.zip -d Paper
mv ~/Paper/RaspberryPiMinecraft-master/* ~/Paper/
Now lets download the Paper Minecraft server and let it build.
chmod +x start.sh
java -jar -Xms800M -Xmx800M paperclip.jar
The first time you will get kicked out and be told that you need to accept the eula. Type/paste the following:
and change the accept line from false to true. Press Ctrl+X to exit and enter y for yes to save our changes.
Now simply run it again. This time it should run. It will take some time because it will download the vanilla server and then apply the performance enhancing patches to it.
java -jar -Xms800M -Xmx800M paperclip.jar
If everything builds successfully the server will actually completely start this time. Once the server has started and you see something like “Timings Reset” go ahead and type stop in the server console and the server will gracefully close. We still have some optimization to do before we can run the server with any kind of stability/performance, but our initial setup is now done. I would not try playing on it just yet though as we still need to configure the server and it will run like garbage without the correct flags and optimizations. If you have made it this far, you are getting very close. We now just need to do our advanced optimizations and we will be ready to roll.
Advanced Raspberry Pi Configuration – Overclock SD card reader
To get a well performing server we need to make some changes to the Raspberry Pi configuration. The first and most important change that we need to make is that we need to overclock the SD port from 50hz to 100hz. This is safe for all modern cards. Unless you have a 2 dollar bargain bin card you shouldn’t have any trouble.
To understand why the Raspberry Pi is so underclocked keep in mind that the Raspberry Pi is designed to work with any piece of junk SD card since it is an educational computer shipped all over the world. They want it to work with as wide of a range of hardware as possible.
Good class 10 SD cards are rated to work at 100hz. If you have a Samsung Evo or a good SanDisk class 10 you will see tremendous performance gains by changing this. This is the most important optimization/overclock you can make to your Pi because I/O performance WILL be a major bottleneck for the Minecraft Pi server!
This overclock option is enabled in your /boot/config.txt. So before we change anything we are going to back it up. Type this command:
sudo cp /boot/config.txt /boot/config.txt.backup
Great. Now we have a backup of our original config.txt located in the boot folder. Next let’s overclock the SD card slot.
sudo nano /boot/config.txt
Now we want to type/paste this line into the file (I put it at the bottom usually, but you can put it anywhere). The # sign in this configuration file indicates a comment, but I have left a comment on it to make it clear what each line does.
# Overclock the SD card port to 100hz
Ctrl+X and yes to save. That’s it. Now let’s reboot the Pi by typing
sudo reboot and if you have a quality card your Raspberry Pi will boot up. This nearly doubles the performance of your SD card provided you are using a high quality microUSB card from the links posted above.
If anything goes wrong and your Pi won’t boot, you can simply put the SD card into another machine and open the /boot/config.txt and change it back to the original. Then restart your Pi and it will load up with the original configuration settings. If this happens it means you probably don’t have a card that can handle a 100hz microSD overclock.
Pregenerate your world
The biggest bottleneck on the Raspberry Pi is that generating “chunks” or basically sections of the Minecraft map is done by the server as you explore. This is a very expensive operation both in CPU usage and disk I/O. If you have several people exploring a server that is brand new and the chunks haven’t been generated things get really slow really quick.
Fortunately, there is a plugin that offers a solution to this problem. It is a plugin called “WorldBorder”. The plugin allows you to set a border on your world that stops people from going further, but this isn’t the feature we are necessarily interested in. WorldBorder has an option to “fill” all of the chunks in your server inside your defined border. This means we can generate all of the chunks before the players reach them so that all the Raspberry Pi has to do is read the chunks from the disk which is MUCH faster than having to generate the chunk from scratch and then save it to the disk.
To download this plugin, make sure that the server is not running, and type the following commands:
wget --content-disposition -E https://dev.bukkit.org/projects/worldborder/files/latest
That’s it. The plugin is now installed.
Before we run the server we need to install one more package. It is an application called “screen” that will allow you to run the Minecraft server on the Pi without having to keep your SSH connection open. Type the following command:
sudo apt-get install screen
In our configuration files we extracted earlier you may have noticed we extracted a script called start.sh. This is a special startup script that uses JVM arguments to help the Minecraft server run appropriately on the Raspberry Pi. I have had Aikar (the master of timings and author of many of the optimizations present in the Paper/Spigot fork of Minecraft) check these JVM arguments and they are the best we can do for the Raspberry Pi and they do make a significant difference.
This is the minimum required to get things running but there are several optional optimizations you should making that I will explain in the next sections. You can start the server by going into the paper directory and running start.sh. This is how it will look when you type the commands:
At first you won’t really see anything happen. To actually see the Minecraft server screen you will type the following command:
screen -r minecraft
You should now see the Minecraft server output and can interact with the console and type commands per usual. The great thing about screen is that even when you close the SSH window your Minecraft server will stay running. If you close your SSH window and want to log back into SSH you simply reattach to the screen by typing screen -r minecraft once again. This will bring the screen back up again.
Go ahead and bring up the Minecraft server back up now by typing:
screen -r minecraft
If the server has completely loaded you should see something at the bottom like “Timings Reset”. This is one of the last lines that prints as the server starts. You can type console commands to the server from here. We are going to use WorldBorder to create a border and then use the fill function to pregenerate the world. This is so that the Pi doesn’t have to create the world dynamically as you are trying to play. These commands will set a worldborder radius of 1000 blocks. The first time I did this I set a radius of 2500 blocks and the server ended up being about 350mb and it took hours and we will probably never go to most of those places. You can adjust this number based on how big you want the world to be. I recommend starting with something like 1000. Remember, this can be adjusted later. Use the following commands:
wb world set 1000 spawn
wb world fill 1000
wb fill confirm
This process will take quite a while. On my overclocked Pi I was getting only 50-60 chunks generated per output message. This shows how important it is to pregenerate your world. If you weren’t doing this, this process would be happening while you were trying to play the server and exploring chunks you had not been to before.
This is one of the biggest secrets to having a playable Pi Minecraft server that nobody ever told you! This process took about 30-45 minutes on my overclocked Pi3 with a great SD card for 1000 blocks. It may take shorter/longer depending on how fast your SD card is and what revision of the Pi you are using.
Okay, now that you have waited and the process is 100% complete, you are done! Type stop to gracefully close the server and make sure all those generated chunks are saved. Now I recommend completely rebooting your Pi to clear out the cache with sudo reboot and get a fresh boot and then heading to your Paper folder and typing ./start.sh.
Connecting to the server
Open your Minecraft client and launch vanilla 1.12. The beauty of the Paper fork is that we will be using the vanilla client to play without any mods. Neither you or your friends will change anything from your vanilla Minecraft client. Launch 1.12 and then head to the multiplayer section. Choose “Add Server” and type in your Pi’s IP address. You should see the Pi server and now be able to connect.
To allow outside players to connect to your network you will need to first find out your public IP address (the internet facing IP address). The easiest way to do this is just to go to http://www.whatismypublicip.com/.
Now that you know your public IP address you need to set up a port forwarding rule in your router. This process is different for every router. If you don’t know how to log into your router and add a port forwarding rule go look at your router and find the model # and then go to google and type your router’s model along with “port forwarding” and you should easily find instructions for any router.
If you already know how to log into your router and add port forwarding, you will simply add a port forward for TCP/UDP port 25565 to your Raspberry Pi’s IP and players outside the network will be able to connect by adding your internet facing IP we got from whatismypublicip.com.
Congratulations, you are done and will now have a well performing Raspberry Pi server!
The reason we are able to run a Minecraft server at full vanilla settings with this configuration is because of the Raspberry Pi’s bottlenecks and how we have minimized them. Let’s recap them real quick.
- Disk I/O: By overclocking the SD port and having a high quality SD card we are able to nearly double our disk performance. Reading is much faster than writing, so by pregenerating our world we are able to use a full view distance of 10 instead of 4 like the other tutorials recommend
- RAM: By running a completely headless server and changing our dedicated video memory to 16mb we squeeze out enough RAM for the Minecraft server to comfortably support a few players at vanilla settings
- CPU: The CPU on the Raspberry Pi is actually fairly decent, but most of Minecraft’s code is single threaded meaning most of the operations are running on one core. The Paper Spigot fork of Minecraft adds threading for some extremely important areas. The most important one is chunk loading and unloading. The vanilla Minecraft server does not do this and that is why it is practically impossible to run a pure vanilla Minecraft server on a quad core ARM computer when everything is in a single thread.
As you saw when we ran WorldBorder’s fill function, the Minecraft server on a Pi can only generate around 50-60 chunks per second. When somebody logs into a server with view distance 10, they can see MANY more chunks than that. That means that if you try to explore with your friends you are generating a huge amount of chunks which brings the Raspberry Pi to its knees.
By pregenerating the world all the Pi has to do is load it and send it. The Pi’s fastest disk performance is reading, so since we are just reading the chunks and sending them instead of generating them (CPU and RAM expensive) and then saving those chunks to the disk (Disk IO intensive), we avoid all this by just reading them and forwarding them to the players. This creates a smooth playable experience.
Therefore, the conclusion of this project is that the key to running a Minecraft server on the Pi is to invest in a excellent solid state drive or SD card and overclock it, then pregenerate your world!