How to program Minecraft with Python on a Raspberry Pi?

Raspberry Pi OS (Desktop version) comes with Minecraft installed. And it’s not (only) to play.
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. I’ll show you how to do this.

An API is available on Minecraft Pi. Everything is preinstalled on Raspberry Pi OS, so it can be directly used in Python, via an editor like Thonny for example.

Just open Minecraft Pi on one side, and Thonny on the other side of your screen, and I will show you how to do this.
By the way, if you have a Raspberry Pi 4, it will be easier for you, as you can work on two screens: one with Minecraft and the other one with your Python Editor.

Let’s see how to do this!

Tools introduction


If you have lived in a cave the last ten years, here’s a short introduction to Minecraft 🙂

Minecraft is a sandbox game where the entire world is generated with blocks of the same size/
The player spawns in this environment and must survive while doing anything that he wants.
The game includes a mix/of exploration, building, crafting, and combat
Yes, you can also fight with passive or hostile 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, there is a hot bar to take another block.
And on the right, you can see the current block you have in your hand.

Raspberry Pi Bootcamp
Sale: 10% off today.
Take it to the next level.
I'm here to help you get started on Raspberry Pi.
Learn all the skills you need in the correct order.

Python language

Python is a programming language often used on Raspberry Pi, but also in a lot of systems (Google frequently 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. It’s normal to try your project first in Python on a Raspberry Pi. It’s one of the few ways to code things in Minecraft Pi 🙂


As I said in the introduction, Raspberry Pi OS 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 a single file, saved on my disk, rather than typing each line into the Python Shell and losing it later.

Here’s what the interface looks like:

thonny empty editor python

Comfortable installation

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

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

I’ve tried remote access to make this tutorial from my computer, but Minecraft’s screen only displays on the Raspberry Pi, I only have the console on remote access software.
It can help with 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 setup will make all the steps below easier.

I also tried working 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.

Program Minecraft with Python

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

Prepare the Minecraft client

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. It’s normal if you can see the console behind.
  • 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 for the world to generate

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

Understand Minecraft logic

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 always flying and 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. In survival mode, it depends on the tools you use (wood tools are slower than diamonds tools for example).

Lean how to control your player

Here are all of 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 enables the fly mode and then use flying to gain altitude
  • Access inventory: E
  • Pause/Quit: ESC

Try to move around a little bit in your world to become at ease with movements.

Master your Raspberry Pi in 30 days
Sale: 10% off today.
Download the eBook.
Uncover the secrets of the Raspberry Pi in a 30 days challenge.
Learn useful Linux skills and practice multiples projects.

First Python script: Hello world

Let’s start with the code part.

Start Thonny

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

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

Interact with Minecraft from a Python script

In each new language, the first thing to learn is how to code the renowned “Hello World!”
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 it (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 happens in the Minecraft window:

hello world minecraft pi

Minecraft API explanations

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 to every code when using 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 the message between brackets.
Good work, you know how to send a message in Minecraft from your Python code.

Change a Minecraft block with Python

Now, we can try something funny!
We can switch blocks, but first I need to give you more information about Minecraft.

Minecraft coordinates

Minecraft uses coordinates to know each player’s 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 of these values changes by 1 . 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 can use it to make funny things.

Minecraft blocks IDs

The second thing you need to know is how to define a block type in Minecraft.

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

minecraft blocks

Basically, each block in the game has an ID.
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 IDs:

Hopefully, they have the same IDs in Minecraft and Minecraft Pi because this site is 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 as before.
The only difference is that we use the setBlock function.
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 to the player.

diamond minecraft

Here is the result in Minecraft:
When I ran the code, I saw a diamond block appear near me.

Nice, but the title says “under the player”, how do you do that?

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 have a diamond block under my feet 🙂
I used the player.getPos() function to get the player coordinates in real-time.
Then I used them to set the block exactly where I wanted it(with y-1 to set it just under).

Now you know the basics, so we can move to more complex concepts!

API discovery

In this part, I’ll explain all of the possibilities you have to code your Minecraft game.
I’ll give you the list of functions you can use.

I didn’t find an official API reference. I don’t know if Mojang has 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, 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.

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?

Try these questions without checking the answer part.


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

minecraft pi teleport player

This function does exactly what we need: teleports 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 you choose 50 because 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.
So the only thing I need to teach you is how to wait 10 seconds.

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 earlier, 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 ourselves.
You already know how to get the player positions and how to place blocks near him.
So, it’s pretty easy!

House foundation

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 a zone to directly 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 the walls and roof alone, it’s exactly the same thing.
If it’s too easy, try to add some windows 🙂

Entire house

minecraft house in python

Here is the small house I built with my script:
Yes, I know … I’m good 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 door.

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

Block interaction

The last thing I want to show you are the block interactions.
There is a way to detect player interaction through the use of block and trigger actions.

This code is difficult to guess for a beginner, so I’ll give it directly and explain each line afterward.
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:

  • This code turns each block you touch in the game (right-click) into 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 change the block (setBlock).

Copy this code in Thonny, run it, and try it.
Try to change it 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 which are not explained in this article.
To go further, you will need to learn algorithmic basics and Python.

Related questions

Is there a way to do multi-player? I have not tested this but it seems possible to join a network game in the main menu, so it should be. This opens fun 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 of the Minecraft API (conditions, loops, and 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 playing the PC version, you’ll see a lot of differences. There is no configuration menu, no mobs, and fewer blocks. You can’t even join a server or add a texture pack. It’s good for coding purposes, but that’s all. If you want more features, you should buy the standard version (available for Linux, so it can work on Raspberry Pi).


If you have followed this entire tutorial, you should know a good part of the Minecraft API.
And hopefully, you understand the API reference.
That way you’ll be able to create everything.

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

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

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?

  2. Does one need to pay for Minecraft to do this? When I try to open Minecraft it wants me to sign into an account? Thanks!

    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 Posts

Master your Raspberry Pi - 10% off