Intro Image

Build a Vanilla Minecraft Server on Raspberry Pi

Notice: The instructions for 1.13 will be delayed for a couple of point releases as it is still too buggy.

Building 1.13 Spigot.jar works and can be used for testing. It is recommended to build a new world and not upgrade an existing one. If you decide to upgrade an existing world you MUST backup your current world as it is likely that weird things will happen.

Follow the instructions as normal but use --rev 1.13 instead of --rev 1.12.2 in step 4c. Download the latest BuildTools.jar in step 4b.

Building a full Linux vanilla server? See the Linux server install documentation.
Building a full Linux modded server? See the Modded Linux server install documentation.

Minecraft Server Version: 1.12.2
Oracle Java Version: 8u181

Approximate time to complete: 1 to 1.5 hours (including build time).

Step 1 - Download Java
Step 2 - Configure Java
Step 3 - Setup Your Environment
Step 4 - Install Minecraft
Step 5 - Configure your new Spigot Minecraft Server
Step 6 - Optional-- Configure Minecraft to start on bootup
Step 7 - Connect to Your Server
Step 8 - Hardening Your Minecraft Server if Visible on the Internet
Step 9 - Backup Your Server Frequently
Step 10 - Upgrading Your Minecraft Server
Step 11 - Recovering a Corrupted World
Step 12 - Creating Automatic Backups

Get a $10 credit towards a dedicated server with DigitalOcean by using this link.

Report errors in this guide. Your feedback is appreciated.

Raspberry Pi Revision

I recommend using a Raspberry Pi Model 3 or 3B which has one GigaByte of RAM and a quad core ARM cpu. Earlier versions, like the Pi A and B or even the low power PiZero are just too lightweight and will result in frustration. I am sure somebody somewhere has tweaked these versions to run a minecraft server well enough, but this build assumes a RaspberryPi 3 running Raspbian Stretch. If you have a model 2 it will likely work, but not as well as the 3.

Raspbian can be downloaded at

I prefer the Raspbian Stretch Lite image, but the full version of Raspbian Stretch with Desktop or installing via NOOBS should be fine. There are many tutorials out there so I will not recreate that here.

Who Is This For?

A Raspberry Pi is a good solution for a small minecraft server. Use the Raspberry Pi for light basic vanilla survival or creative world needs. If your focus is a small lan server for family and friends then this will work for you and is fully workable for less than five people. Use it to learn about managing minecraft servers. These skills are directly portable to setting up a bigger server on dedicated Linux hardware with Intel/AMD processors. Raspbian is based on Debian so the instructions would work on all Debian based servers like Ubuntu for example, with minor differences.

However, if you are into mods, redstone, highly complex automated farms and want to play with more than five people at once then this is not the solution for you. In those cases you need a beefier system with a better CPU and more RAM. A rented server with a company like MCProhosting will give you what you need, including an enterprise level network connection that has a Service Level Agreement behind it. At home you most likely have an inferior residential service that is less suitable for network play. If your needs are this great then a Raspberry Pi will only lead to frustration for you.

Step 1 - Download Java

Minecraft Server requires Oracle Java to run. You can install it on Raspbian with apt-get but that will give you an older version. Instead, get the latest available directly from Oracle.

a) Login to your pi via ssh

via Linux:   ssh pi@address of your pi
via Windows: Connect using a SSH client such as Putty

b) Download the latest version of Java (32bit) for ARM and copy it to the /opt folder on your pi.

Latest Version of Java
Java Version

You can also download Oracle Java directly from the command line on your pi using wget. Oracle requires that you accept the license agreement, so the direct download command requires a little trickery in order to bypass this. The following three commands will change the directory to /opt, download directly from Oracle and then extract the contents of the file to the opt folder. Copy/paste and run each command one at a time.

cd /opt

wget --no-cookies --no-check-certificate --header "Cookie:; oraclelicense=accept-securebackup-cookie"

sudo tar -zxvf jdk-8u181-linux-arm32-vfp-hflt.tar.gz

Step 2 - Configure Java

a) The next step will be to setup the Java environment so that your system recognizes how to access both the java binary and java compiler which will be required when building your minecraft server.

    sudo update-alternatives --install /usr/bin/java java /opt/jdk1.8.0_181/bin/java 1
    sudo update-alternatives --install /usr/bin/javac javac /opt/jdk1.8.0_181/bin/javac 1
b) Set this version of java (and the compiler) as your default versions. These commands will give you a list of versions to select, just select the right version option. If this is the only version on your pi then it will tell you so and select that one automatically. Do the same for the java compiler (javac).
    sudo update-alternatives --config java
    sudo update-alternatives --config javac
c) Finally, check your version to make sure you are using the right one
    java -version

You should see the following;

    java version "1.8.0_181"
    Java(TM) SE Runtime Environment (build 1.8.0_181-b13)
    Java HotSpot(TM) Client VM (build 25.181-b13, mixed mode)

    javac -version

You should see the following;
    javac 1.8.0_181

Optional - Removing Old Versions of Java

Old versions of java won't affect anything if you have plenty of disk space. To save a bit of space on your disk you can remove old versions that are no longer used. Simply remove the links to the binaries with update-alternatives and delete the java folder. To remove version 1.8.0_121 for example;

a) remove the link

    sudo update-alternatives --remove "java" "/opt/jdk1.8.0_121/bin/java"
    sudo update-alternatives --remove "javac" "/opt/jdk1.8.0_121/bin/javac"
b) remove the folder (be careful whenever using rm -r -f, a misplaced "/" or "*" could/will mess up your system)
    cd /opt
    sudo rm -r -f jdk1.8.0_121

Step 3 - Setup Your Environment

a) This is a good time to do a full upgrade of your pi
    sudo apt-get update && sudo apt-get -y upgrade
b) Install git
    sudo apt-get install git
c) Install screen (This will be needed to run your minecraft server console while logged out of the pi).
    sudo apt-get install screen

Step 4 - Install Minecraft

We are going to install the Spigot Minecraft Server build. This build is an excellent choice for a low resource system like a Raspberry Pi.

a) create the folder

    cd /home/pi
    mkdir minecraft
    cd minecraft
b) download the buildtools
c) build the server
   sudo java -jar BuildTools.jar --rev 1.12.2
This would be a good time to get yourself a beverage. The size of the compiled jar file has jumped from about 22MB in version 1.11.x to 41MB under version 1.12.x. As a result it now takes about 50 minutes to build on a Pi3 and almost an hour and half on a Pi2.

Update: May 9 2018 Not sure what changed but building on a Pi3 only took 10 minutes today. I do not have a Pi2 anymore so I cannot comment on that version.

Be patient and come back in a bit. If all goes well you will have a file called spigot-1.12.2.jar (or whatever the latest version is at the time) in your minecraft folder.

If you have access to a faster Linux system you can always compile it on that system and copy the jar file to the raspberry pi, thus saving yourself quite a bit of time.

If you are still having problems, another alternative is to download this spigot jar file that I compiled on my own system. It is always best for security reasons to compile your own, but this file is provided with a GPG signature and its SHA256 hash which you can verify on your own system before using.

Step 5 - Configure your new Spigot Minecraft Server

a) run the server for the first time. Make sure you are in the /home/pi/minecraft directory.
    sudo java -Xms512M -Xmx1008M -jar /home/pi/minecraft/spigot-1.12.2.jar nogui  
*Note: Make sure to enter the right version that you have built. At the time of this writing Minecraft 1.12.2 was the latest version

b) accept the EULA. The first time you try to run your minecraft server you will be required to accept the EULA.

    sudo nano eula.txt
c) Change the following line to true and save the file
d) Run the server a second time to generate your world. World generation will take a while the first time. Subsequent server starts will be much quicker.
Before doing this, you can download the following file and replace the one that was created automatically. (or copy/paste directly to your existing file from the console).
This file will give you a standard survival world on normal difficulty.

Edit the file with your preferred seed if you have one and it will generate the world that you specify.
Minecraft Atlas is great site to find new interesting seeds. Although the site says Minecraft 1.8, the seeds are compatible with 1.12.2
View the Wiki for all configuration options.
    sudo nano
    change the following line with your preferred seed directly after the = sign
    If you leave it blank Minecraft will generate a random world on first launch
On a Pi2 I changed the line view-distance to 4. You can tweak this up a little to 6 or 8 but if you find yourself getting some lag bring it back down a little. On a Pi3 I run it at 8 but have went as high as 10. If you get some lag bring it down a little.
    sudo java -Xms512M -Xmx1008M -jar /home/pi/minecraft/spigot-1.12.2.jar nogui   
e) Stop your server and install the NoSpawnChunks plugin. To stop your server, in the minecraft console type 'stop' and hit enter.
Download the latest NoSpawnChunks plugin and copy it to your /home/pi/minecraft/plugins folder.
    cd /home/pi/minecraft
    mkdir plugins   
    cd plugins   <-- Insert the file you downloaded here
f) make things a little easier on yourself by using a script to start minecraft
    mkdir /home/pi/startup
    cd /home/pi/startup
g) Copy and paste the following in your file
    cd /home/pi/minecraft/ && java -Xms512M -Xmx1008M -jar /home/pi/minecraft/spigot-1.12.2.jar nogui
h) Save the file and make it executable
    chmod +x
i) Start your server
    screen <---hit enter at the informational message
    sudo /home/pi/startup/
    To exit the screen session hit 'CTRL AD'

Step 6 - Optional-- Configure Minecraft to start on bootup.

a) Add a command to /etc/rc.local to start your Minecraft server everytime the Pi boots up.
    sudo nano /etc/rc.local
Right before the last line 'exit 0' add the following command, save and exit the file. This will allow the minecraft server to start in a detached screen session when the Pi boots up.
    screen -dm -S minecraft /home/pi/startup/ 
b) To access your console after bootup use the following command;
    sudo screen -r minecraft
    To exit the screen session use the following command

Step 7 - Connect to Your Server

a) In Minecraft select the Multiplayer button

b) Click the Add Server button
c) Edit the Server Info as follows (insert the IP address of your Raspberry Pi)

Add Server Image

d) Enter your world for the first time and have fun!!!

New Server Image

Step 8 - Hardening Your Minecraft Server if Visible on the Internet

If you want friends to access the server from outside your home network you will have to forward external requests to port 25565 on your router to your Pi. Check the documentation for your router.

If your Pi is connected directly to the internet with a public IP address then you need to setup your own firewall. Check out my documentation for setting up The Linux Five Minute Firewall. This method works great on Raspbian.

Activate whitelisting. It is extremely important to activate whitelisting if your server is visible on the internet. Port 25565 is a popular port and is actively scanned by all kinds of people using automated scripts. They are looking for open servers so they can login and cause havoc on your world. Whitelisting will stop unauthorized users from joining your world.
In your set the following value to true;

Restart your minecraft server and run the following command at the console for each user you would like to allow.
    whitelist add minecraft_user1
    whitelist add minecraft_user2

To remove a user

    whitelist remove minecraft_user2   
When an unauthorized user tries to connect to your server they will simply get a message that they are not whitelisted and will be turned away.

Step 9 - Backup Your Server Frequently

To backup your server do the following;
    login to your pi
    cd ~
    tar -zcvf minecraft_backup.tar.gz minecraft
    copy the minecraft_backup.tar.gz to a safe location, preferably another computer.  This file can be 
    used to restore your world if needed.
    Get into the habit of doing this regularly.  You can even use the cron scheduler to automate the 
    process at a specified time each day as explained in Step 12.

Step 10 - Upgrading Your Minecraft Server

You've done it. You have successfully built your Minecraft Server. Of course Mojang will release a new version the very next day and all your friends will complain that they can no longer connect. No problem, upgrading your server to the latest version couldn't be easier.

a) First thing you need to do is backup your world. Just like in Step 9 we will do the following;

    login to your pi and stop your minecraft server. In the minecraft console type 'stop' and hit enter.
    cd ~
    tar -zcvf minecraft_backup_version1.12.1.tar.gz minecraft   
b) download the latest buildtools
    cd /home/pi/minecraft
    wget -O BuildTools.jar
c) build the new server. This will take a while, but if all goes well you should see a new spigot jar file.
   sudo java -jar BuildTools.jar --rev 1.12.2
Compiling your own is better, but I do make jar files that I have compiled available if needed. Files are signed with my gpg key and have a SHA256 hash that you can use to verify the integrity of the file.

jar file download

d) Update your startup script to use the latest jar file

    cd /home/pi/startup
    Update the command to start the new jar file
    cd /home/pi/minecraft/ && java -Xms512M -Xmx1008M -jar /home/pi/minecraft/spigot-1.12.2.jar nogui
    Save the file
e) Restart your server by either running your startup script with sudo or reboot your pi if you configured it to start on boot.

Step 11 - Recovering a Corrupted World

The importance of regular backups cannot be overstated. It happens, you try to log into your awesome minecraft world and you see exception errors only. Or you enter the world and all kinds of things have disappeared, your sweet enchanted sword is gone, your diamonds chest is empty. Hours of work and play are now destroyed. Your world may have corrupted for any number of issues such as software problems or card corruption.

If you did your backups like we discussed in Step 9 then you are laughing. To restore your previous backup do the following;

Delete your existing minecraft folder

    cd ~
    sudo rm -r -f minecraft  
copy your previously saved minecraft.tar.gz file to your /home/pi folder.

restore your world

    tar -zxvf minecraft.tar.gz

That's it, restart your server and you have successfully restored from your last good backup. Any changes you made since that backup are gone, so it is important to do your backups regularly.

Step 12 - Creating Automatic Backups

These instructions will help you create automatic backups of your minecraft world, so that you don't have to worry about remembering. These instructions will do the following;

1) Provide a ready to use script to initiate the backup
2) Configure the cron scheduler to start the backup at 2:02am everyday
3) Name the backup day_of_week-minecraft-.tar.gz

This will create a 7 day rotation of backups with the oldest being overwritten with a new one.

a) Create a place for your script.

    cd ~
    mkdir scripts
    cd scripts
b) copy and paste this script into your file you have open in the nano editor. Change the dest= line to point to the folder you want your backups to reside in.

# Backup minecraft world to a
# specified folder.

# What to backup.  Name of minecraft folder

# Where to backup to. I backup to an external hd connected
# to my Pi.  enter the folder name where you want your backups to go.
# Just make sure you have enough space to hold 7 days of backups. This
# can be on the pi itself, to an external hard drive or mounted network share.

# Create backup archive filename.
day=$(date +%A)

# Backup the files using tar.
cd /home/pi && tar zcvf $dest/$archive_file $backup_files

c) Save the file by pressing CTRL-X and entering Y

d) Make the file executable

    chmod +x
e) Test your script. Before creating the scheduled task ensure your script works


You should see the backup happening. Once completed open the file it created which should be in the location that you specified. Once you have confirmed that your backup works, create a scheduled task to automate the backups.

f) Create a scheduled task with the cron scheduler

    crontab -e
Enter this line at the end of your crontab and then save it.
    02 2 * * * /home/pi/scripts/ &> /dev/null
This will create your backup every day at 2:02 am. That's it, in your folder where you specified your backups to be created you will have the following after one week;

Every day your oldest file will be replaced with the new backup giving you 7 days of backups.

That's it! Now have fun! I hope these instructions were helpful and that you learned a bit of how a Minecraft server functions.


If you found these instructions helpful a small donation is appreciated. I will be keeping these instructions up to date with the latest versions of Minecraft and Oracle Java.

Litecoin - LUng4qHHi7LhiAB3YGEwYoNEPJn78zaJwP
Bitcoin - 3JTdnx2FcWK8peZqtafQUh195dZR6XE8ha


Copyright © 2018 Al Audet