program minecraft on raspberry pi

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.

By the way, if you get overwhelmed as soon as Python is required for a project, I recommend checking out my e-book “Master Python on Raspberry Pi“. It will guide you step-by-step to learn the essential concepts (and only the essential concepts) required to achieve any project in the future. Raspberry Pi without Python is like a car without an engine, you miss all the fun parts. Get 10% off by downloading it today!

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.

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

Install Minecraft Pi Reborn (if needed)

On Raspberry Pi OS Bullseye, Minecraft Pi is no longer installed by default. If you want to follow this tutorial, you need to install it manually first.
The easiest way I found is to download and use “Minecraft Pi Reborn” from this repository on GitHub.

  • Download the latest client package for your architecture (direct link).
  • Add the execution permissions to anybody (right-click > Properties > Permissions).
  • Double-click on it to start the game.

You can then follow the next steps as with any Raspberry Pi OS versions.
You may also need to install the Python library manually:
sudo apt install python3-minecraftpi

Note: On Raspberry Pi 5, Minecraft Pi Reborn will crash on start, due to the 16K page size. The only way to run it (for now) is to add this line to /boot/config.txt:
Issue opened here if you want to follow the updates.

Grab my Python cheat sheet!
If like me, you always mix the languages syntax, download my cheat sheet for Python here!
Download now

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.

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.

Join Our Community!

Connect, learn, and grow with other Raspberry Pi enthusiasts. Support RaspberryTips and enjoy an ad-free reading experience. Get exclusive monthly video tutorials and many other benefits.

Learn more

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 …

Grab my Python cheat sheet!
If like me, you always mix the languages syntax, download my cheat sheet for Python here!
Download now

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.

Download Your Essential Linux Commands Guide!
It's a free PDF guide containing every Raspberry Pi Linux command you should know!
Download now

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. 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).

Download Your Essential Linux Commands Guide!
It's a free PDF guide containing every Raspberry Pi Linux command you should know!
Download now

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

Reminder: Remember that all the members of my community get access to this website without ads, exclusive courses and much more. You can become part of this community for as little as $5 per month & get all the benefits immediately.


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.

And if you are looking for other fun projects to experiment with Python, I highly recommend testing a robot kit for your Raspberry Pi. I have a lot of fun each time I try one of these kits, it’s like putting everything together. I also have a list of interesting projects for Python and Raspberry Pi here.

Whenever you’re ready, here are other ways I can help you:

The RaspberryTips Community: If you want to hang out with me and other Raspberry Pi fans, you can join the community. I share exclusive tutorials and behind-the-scenes content there. Premium members can also visit the website without ads.

Master your Raspberry Pi in 30 days: If you are looking for the best tips to become an expert on Raspberry Pi, this book is for you. Learn useful Linux skills and practice multiple projects with step-by-step guides.

The Raspberry Pi Bootcamp: Understand everything about the Raspberry Pi, stop searching for help all the time, and finally enjoy completing your projects.

Master Python on Raspberry Pi: Create, understand, and improve any Python script for your Raspberry Pi. Learn the essentials step-by-step without losing time understanding useless concepts.

You can also find all my recommendations for tools and hardware on this page.

Similar Posts


  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

  3. I followed the instructions to the letter, but nothing happened. Specifically:

    First, I launched Minecraft on the raspberry pi, and tested it out. All of the player controls work fine.

    Next, I opened Thonny alonside it and typed in the following:
    from mcpi.minecraft import Minecraft
    mc = Minecraft.create()
    mc.postToChat(“Hello world”)

    Then saved the file and clicked the green arrow to run the script. Nothing changed on the Minecraft window. No chat bar. No “hello world.” What did I do wrong?

  4. I used geany instead of thonny and it worked great! The code is good and I learned so much! Hope you will keep making articals to help people!

    -Harper (:

  5. i add a while(1): to the code that makes blocks spawn under you and made a sort of block trail that you can scaffold with

Comments are closed.