How to program Minecraft with Python on a Raspberry Pi?

As you probably noticed, Raspbian (Desktop version) comes with Minecraft already installed
And it’s not (only) to play
If you don’t know, the main goal for the Raspberry Pi Foundation is to help young people learn how to compute and program
They installed Minecraft Pi to help kids achieve this goal while having fun

How to program Minecraft with Python on a Raspberry Pi?
On a fresh Raspbian Desktop installation, you get all you need to program Minecraft:
– Minecraft Pi is available in the “Games” menu
– Python editors are also available directly in the “Programming” menu (Python 3 (IDLE) and Thonny Python IDE)

So you already have everything you need to play Minecraft from a different way: by programming it
Let’s see how to do this

Tools introduction


If you lived in a cave the last ten years, I’ll make a short introduction about Minecraft 🙂

Minecraft is a sandbox game where the entire world is generated with blocks from the same size
The player spawns in this environment and must survive while doing anything what he wants
The game includes a mix of exploration, building, crafting and combat
Yes, you can also fight with passive or hostiles mobs (like zombies or cows)

Here is what it looks like when you start the game on a Raspberry Pi:

minecraft world on raspberry pi

At the bottom, you get a hot bar to take another block
And on the right you see the current block you have in your hand

Python language

Python is a programming language often used on Raspberry Pi, but also in a lot of systems (Google often uses Python in its projects)
Python offers a simple syntax and allows us to add libraries (like the Minecraft library we’ll use later)

Python and Raspberry Pi stories are nested, and it’s normal to make a first try in Python for every project on a Raspberry Pi
And to code things in Minecraft Pi, it’s maybe the only way 🙂


As I said in the introduction, Raspbian offers several Python editors already included on a fresh install
For this tutorial, we’ll use “Thonny”
If you prefer another one, you can do the same thing
But I like keeping each exercise in an entire file, saved on my disk, rather than typing each line in the Python Shell and losing it after

Here’s what the interface looks like:

thonny empty editor python

Comfortable installation

Do you have a good installation? Like classic keyboard and mouse, desk and screen?
If not, I recommend starting with this

In my case, I only have a mini Bluetooth keyboard with a touch pad
It’s not the easiest way to make code

I’ve tried remote access to make this tutorial from my computer, but the Minecraft’s screen only displays on the Raspberry Pi, on any remote access software I only have the console
It can help for typing the code, but it’s not convenient

So if possible, put your Raspberry Pi on a desk with a keyboard, mouse and screen
This will be easier to make all the things below

I also tried in a virtual machine, but there is no way to get Minecraft Pi
It’s only working with an ARM CPU, and I have no solution to emulate this architecture

First steps

In this part, we’ll start with basic things like a first game and simple python commands

First steps in Minecraft

Create a new world

The first thing to do is to start the game and create a new world

  • Start the game (Start Menu > Games > Minecraft Pi)
    The window is a little buggy. You see the console behind, it’s normal
  • Try to put the game on a side of your screen, you’ll need space for the Python editor later
    To move the window, click on the console blue bar with the small cursor (yes you have two …)
  • Then click on “Start Game”
  • You’re now in the “Select world” menu. Click on “Create new” to create your world
    Wait a few seconds during the world generation

You can now control your player with the mouse to see the world around
I’ll give you all the controls keys later

Minecraft game introduction

Minecraft exists in several game modes:

  • Survival: you need to gather blocks and resources, craft stuff and survive during the night
  • Creative: you get all the blocks you want for free and can’t die
  • Adventure: for map creators, you can’t break blocks but you can use levers and buttons
  • Spectator: no interaction, you are flying all the time and you can go through blocks

On Minecraft Pi, as it’s mostly an educative game, you are in the creative mode
You already get a sword and some blocks in the quick bar at the bottom of the screen
It’s possible to get more blocks (see the next paragraph), it’s always sunny and you can’t die

In creative mode it’s possible to break blocks in one shot, while in survival it depends of the tools you use (wood tools are slower than diamonds tools for example)


Here are all the controls you need to know:

  • Camera: Move the mouse
  • Break block: Left mouse
  • Place block: Right mouse
  • Moving: W,S,A,D   (Z,S,Q,D on an AZERTY keyboard)
  • Jumping: Space
    Auto jump is enabled when moving
    Double space enable the fly mode and then use fly to gain altitude
  • Access inventory: E
  • Pause/Quit: ESC

Try to move a little in your world to be at ease with movements

Hello world

Ok let’s start with the code part

Start Thonny

Ok keep Minecraft open on one side and start Thonny
Open the App Menu > Programming > Thonny Python IDE
Then keep the new window on the other side

Under the menu, the big space is for your code (it’s like a file editor)
And under it you have the Python Shell to see what happen when you run or debug the code

First code

In each new language, the first thing to learn is how to code the famous “Hello World!”
So let’s do this!

To start, type this code in Thonny:

from mcpi.minecraft import Minecraft

mc = Minecraft.create()
mc.postToChat("Hello world")
  • Click on “Save” in the top menu
    Save it where you want (ex: /home/pi/
  • Go back to Minecraft to see the game
    Then type “TAB” to free the mouse pointer
  • In the Thonny top menu, click on “Run”

Check what happen in the Minecraft window:

hello world minecraft pi


Let’s see what we have done line by line

  • First line:
    from mcpi.minecraft import Minecraft

    In this line, we include the Minecraft library for Python
    So now, Python knows how to speak with Minecraft
    You must add this line in every code for Minecraft

  • Second line:
    mc = Minecraft.create()

    In this one, we initialize the mc variable
    This variable is the representation of the library in our code
    We’ll use this to do things in Minecraft

  • Third line:
    mc.postToChat("Hello world")

    And the last one is to send a message to Minecraft
    We use the mc variable defined previously and call the function postToChat from the Minecraft library
    This function allows us to send in Minecraft the message between brackets

Good work, you know how to send a message in Minecraft from your Python code

Change a block

Now, we can try something funny
We can switch a block with another one, but first I need to give you more information about Minecraft

Minecraft coordinates

Minecraft use coordinates to know the player position, and each block has a different position
The player’s position is visible in the top left of the Minecraft window:

minecraft position

Try to move and see how it changes
Each time you move one block away, one if these values is changing from 1 too

So, my player position is defined by three values:

  • X: 4.6 – It’s my east/west position
  • Y: 0.0 – It’s my altitude
  • Z: -0.7 – It’s my north/south position

This picture should help you understand:

minecraft coordinates

Try to move your player again in the game and see how the position changes in the indicator
At any time, we know the player position, and we can use it to make funny things

Minecraft blocks IDs

Second things to know is how to define a block type in Minecraft

When you open the inventory (E) you can see that Minecraft have a lot of blocks available:

minecraft blocks

Basically, each block in the game has an ID to define it
Stone is 1, Grass is 2, Dirt is 3, etc …

So if we want to set a specific block near the player, we only need to know its ID
There is a website you can use to get the list of ID:

I hope that they have the same ID in Minecraft and Minecraft Pi because it’s a site for the PC version
We’ll try this
Choose a block from the website list, and note the ID, you’ll need it later

Change a block under the player

Now you’ll type this code in Thonny to set a block at a specific position:

from mcpi.minecraft import Minecraft

mc = Minecraft.create()
mc.setBlock(0, 0, 0, 56)

It’s almost the same code than before
The only difference is that we use the setBlock function instead
Parameters are: x, y, z (position) and the block id

I choose the diamond ore block (ID 56) and the 0/0/0 position (near my player position)
But you can choose what you want, try to set a position close from the player

Here is the result in Minecraft:
diamond minecraftI saw a diamond block appear close to me when I ran the code

Yes nice, but the title say “under the player”, how to do that?

I know, here is the entire code with a minor change:

from mcpi.minecraft import Minecraft

mc = Minecraft.create()
x, y, z = mc.player.getPos()
mc.setBlock(x, y-1, z, 56)

And that’s it, I got a diamond block under my feet 🙂
I used the player.getPos() function to get the player coordinates in real time
And then I used them to set the block exactly where I wanted (with y-1 to set it just under)

I teached you the basics, so now we can move to a little more complex things

API discovery

In this part, I’ll try to explain you all the possibilities you have to code your Minecraft game
I’ll not teach you each function one by one, but I’ll give you the list of function you can use

I didn’t find an official API reference. I don’t know if Mojang have this hidden somewhere, but I didn’t find it
The only page I found is the website linked to the “Adventures in Minecraft” book (check it on Amazon, it’s a great book if you like this kind of tutorial)

This website gives you all the functions, the parameters and explains what they do
Click here to see this page

Teleport the player

The first thing I want you to try is to teleport the player to another place
If you are near 0/0 you could try to go to 1000/1000 thanks to the Python code in one second

If you feel ready, try to write this code yourself before checking the answer


Which API function will you use to do this?
What do you need?

Make a try without checking the answer part


This is easy, in fact we only need one function, this one:

minecraft pi teleport player

This function does exactly what we need: teleport the player somewhere

Here is my first code:

from mcpi.minecraft import Minecraft

mc = Minecraft.create()

If you are in the dark, try other numbers
I put 50 for altitude, because the mountains can be high, and I don’t want to teleport myself under the ground
Maybe you’ll fall if 50 it’s in the air, but you’re in creative mode, so you can’t die

Going further

Now try to use your Python knowledge to improve this script
Let’s say we want to send the player back to his initial position 10 seconds after the teleportation

We already know how to get the player position and how to teleport it
So the only thing I should teach you is how to wait 10 seconds, ok?

Here is the entire code to do this:

from mcpi.minecraft import Minecraft
from time import sleep

mc = Minecraft.create()
x,y,z = mc.player.getPos()

Click on “Run” and try it
You’ll see exactly what I said, teleport, then 10 seconds, then back to the first position
In this code, we import the “sleep” function from the time library (classic library in Python)
We use all the functions already seen and sleep(10) to wait 10 seconds between the two teleportations

Good job, jump to the next exercise!

Build a house

Ok, in this part we want to build a house around the player by placing no blocks ourself
You already know how to get the player positions and how to place blocks near him
So, it’s easy no?

House foundations

To start, we’ll just build the floor
Let’s say a 5×5 zone in wood

If you want to try, let’s go
If not, here is my answer:

from mcpi.minecraft import Minecraft

mc = Minecraft.create()
x, y, z = mc.player.getPos()
mc.setBlocks(x-2, y-1, z-2, x+2, y-1, z+2, 5)

Find a flat place and run the code!
Yes, I cheated 🙂
You can use setBlock 25 times if you want
But setBlocks (with an “s”) allow us to define directly a zone to fill with one block type, like this:

So we need to fill a zone from x-2/y-1/z-2 to x+2/y-1/z+2 to set the 25 blocks

After running the previous code, you should get the floor of your house
Try to build walls and roof alone, it’s exactly the same thing
If it’s too easy, try to add some windows 🙂

Entire house

Here is the small house I build with my script:
minecraft house in pythonYes … I’m not bad with code but I’m not the best Minecraft builder 🙂

The corresponding code is here:

from mcpi.minecraft import Minecraft

mc = Minecraft.create()
x,y,z = mc.player.getPos()

mc.setBlocks(x-2,y-1,z-2,x+2,y-1,z+2,5) #floor
mc.setBlocks(x-2,y,z-2,x-2,y+2,z+2,5) #wall1
mc.setBlocks(x-2,y,z-2,x+2,y+2,z-2,5) #wall2
mc.setBlocks(x+2,y,z-2,x+2,y+2,z+2,5) #wall3
mc.setBlocks(x-2,y,z+2,x+2,y+2,z+2,5) #wall4

mc.setBlocks(x-2,y+3,z-2,x+2,y+3,z+2,17) #roof

mc.setBlock(x-2,y+1,z,20) #window 1
mc.setBlock(x,y+1,z-2,20) #window 2
mc.setBlock(x+2,y+1,z,20) #window 3

mc.setBlock(x,y+1,z+2,0) #door 1
mc.setBlock(x,y,z+2,0) #door 2

Minecraft blocks IDs: 5 is wood, 17 is oak log, 20 is glass and 0 is air

I use setBlocks to create the floor, walls and roof
Then I use setBlock (without “s”) to create the small windows and the door

Once you understand the logic behind this script, you should be able to build what you want in Python

Block interaction

The last thing I want to show you are the block interactions
There is a way to detect a player interaction with a block and trigger actions after this

This code is difficult to guess for a beginner, so I’ll give it directly and explain each line just after
Here is the code I created on this topic:

from mcpi.minecraft import Minecraft
from time import sleep

mc = Minecraft.create()

    while True:
        blockEvents =
        if blockEvents:
            for blockEvent in blockEvents:
                mc.postToChat("Hit detected")
                x,y,z = blockEvent.pos
except KeyboardInterrupt:

Here are some explanations about this:

  • This code turns each block you touch in the game (right-click) in diamond ore
  • pollBlockHits is the main function we use in this code
    You already know the other Minecraft functions
  • As we don’t know when the player will touch a block, we need to create an infinite loop: while True
    The try/except thing is mandatory when you create an infinite loop, to allow an exit (here it’s CTRL+C)
  • We add a timer in this loop to not overload the Raspberry Pi: sleep(1)
  • At the beginning of the loop, we call pollBlockHits to get all the blocks hit by the player
  • If there is a result, we create another loop (for) to browse all results (blockEvent)
  • Finally for each event, we post a message in Minecraft (postToChat)
    And then we change the block (setBlock)

Copy this code in Thonny, run it and try it
Try to change it as you want to be sure you understand my code

If you’re not familiar with programming, it can be difficult
There are notions independent from the Minecraft API here, and you’ll not learn them in one article
To go further, you need to learn algorithmic basics and Python

Related questions

Is there a way to do multi-player? I didn’t test it but it seems possible to join a network game in the main menu, so it should be. This open funs game possibilities. For example, I’m thinking about a Splatoon game using the “Block interaction” code we saw before (each player sets a different block, and the goal is to have the most blocks from your color in a limited area)

How to get the keys pressed by the player? There is no function for this in the Minecraft API reference. But you can get this from the whole system. I think the Pygame library can help you with that.
And more generally, to go further with your Minecraft scripts, you need to learn how to code in Python outside the Minecraft API (conditions, loops, main libraries like the GPIO one)

What are the Minecraft Pi limitations? Minecraft is a paid game. On Raspberry Pi you get a free edition, but it’s an alpha version. If you are used to play the PC version, you’ll see a lot of differences. There is no configuration menu, no mobs, fewer blocks. You can’t even join a server or add a texture pack. It’s good for coding purpose, but that’s all. If you want more, you need to buy the standard version (available for Linux, so it can work on Raspberry Pi)


Here it is, you should already know a good part of the Minecraft API if you followed this tutorial entirely
And the best would be that you understand the API reference
That way you’ll be able to create everything

As I mentioned previously, if you want to go further with Minecraft on Raspberry there is a great book about this: Adventures in Minecraft
If you like Minecraft and programming, it’s a book to have in your collection
I even put it in my top 20 books for Raspberry Pi



Patrick Fromaget

I'm the lead author and owner of My goal is to help you with your Raspberry Pi problems using detailed guides and tutorials. In real life, I'm a Linux system administrator with a web developer experience.

3 thoughts on “How to program Minecraft with Python on a Raspberry Pi?

  1. I tryed this exact code in thonny and its not working….

    it keeps saying invalid syntax even tho I followed everything you typed up do you have any idea?

    1. Hello,
      No, Minecraft Pi Edition doesn’t require any account.
      If your version is asking for it, you probably have the full version, not the Pi edition

Leave a Reply

Your email address will not be published. Required fields are marked *

Recent Content