Updates to Minecraft Documentation – and a Python 3 version is on the way!

No … we’re not adding a Start Menu or a paperclip assistant. This update has nothing to do with Microsoft’s acquisition of Mojang. See the note below for information about this.


You may remember when Mojang released Minecraft: Pi edition for free on Raspberry Pi back in early 2013. If you’re unfamiliar, Minecraft is a popular sandbox open world-building game (like on-screen lego) available for a number of different platforms like PCs, consoles and phones. The Pi edition has a Python programming interface allowing users to use code to build things and manipulate the virtual world around them. It’s a great way to learn coding, and there are plenty of great projects out there people have done and shared with the world.


Last week when we announced the release of the new Raspbian image, we mentioned that Minecraft is now installed by default. Now if you download NOOBS or the standalone Raspbian image, it will come with Minecraft pre-installed. It’s also worth mentioning that the Minecraft application is packaged, so rather than downloading the zip file you can easily install it like a standard application:

sudo apt-get update
sudo apt-get install minecraft-pi

The accompanying Python module will be installed globally along with the game itself you don’t need to save your Python scripts in a particular folder like you did before. If you’re following books, guides, tutorials or worksheets that were written before, the code will still work the same and if you install Minecraft the new way you’ll be able to save your scripts anywhere.

Once it’s installed, here’s the basic setup to get a “Hello world” in Minecraft:

from mcpi import minecraft

mc = minecraft.Minecraft.create()

mc.postToChat("Hello world")


When we launched the new Raspberry Pi website in April it came with a documentation section, which we’ve been expanding ever since. In May we announced the usage guides within this documentation were complete, which features basic how to guides for getting started with each of the main applications on Raspberry Pi.

We’ve just revamped the Minecraft section to explore more of the fundamental components of the Pi edition and its programming interface, including installation, running the game and Python side-by-side, exploring the programming interface and getting a good all-round introduction to what can be done.

You’ll also find this guide in our resources section, and for a full API reference see Martin O’Hanlon’s website stuffaboutcode.com


The edition we have at the moment was built for Python 2, and that’s still the case. However, the education team brought this up at PyConUK at the weekend and a team of developers offered to work on porting it to Python 3 – with some success!


The project is on GitHub and you can download the repository and use it the way you would use the old version of Minecraft (when you downloaded a zip) if you want to test it – just use IDLE 3 instead! We’re also planning to make some improvements to the API to make it more Pythonic and more intuitive. I’m not sure what the timescale will be for the port, but watch this space for news.

Python 3 is really important to us and we’re keen to make sure all libraries people use on the Pi are available in Python 3. Python 2 should not be the default, we should be pushing forward and adapting Python 3. As it says on the Python 2 or Python 3 page on python.org:

Short version: Python 2.x is legacy, Python 3.x is the present and future of the language

So if you’re the maintainer of a Python library, please help by making sure it’s available for Python 3. If you’re using a Python library that’s not available in Python 3 – please let us know so we can add it to the list and we’ll do what we can do get them ported.

One last note about the Microsoft acquisition of the Minecraft development company Mojang: many people have asked us what this means for the future of Minecraft on Raspberry Pi. In statements on their website, Microsoft claim they intend to continue to support Minecraft on all existing platforms. We don’t know for sure what the future will bring but Minecraft is important to us, particularly its use in education, and we’re confident that it won’t be taken from us.


Danilo avatar

I plan on teaching kids how to program using Minecraft. I looked at the existing library, but found it very messy and unpythonic (a lot of Java idioms in there).

Here it is: https://github.com/coredump-ch/pyminecraft Not yet 100% finished, but it will probably be in the future.

Is this of any use to you? I really would not like to teach kids programming with a messy library. But on the other hand I don’t want to maintain another library if one is already preinstalled on the Raspberry Pis…

If someone wants to know more, you can also contact me on twitter: https://twitter.com/dbrgn

Jason avatar

I’ve written a scratch extension app to teach my kids Scratch programming using Minecraft Pi Edition.

Unfortunately Scratch2 doesn’t run on the Pi so we use scratch on a local laptop and the extension app integrates with Minecraft running on the Pi using the python api.

If someone wants to give it a try its at:

Tim Rowledge avatar

We can probably make a similar facility available for the Pi Scratch at some point; it’s just a matter of programming. The new version has a fresh beta release available; https://github.com/raspberrypi/scratch/blob/master/NuScratchBeta9.tgz

Ben Nuttall avatar

There’s also a project for controlling Minecraft from Scratch – all running on Raspberry Pi. Its maintainer is Japanese so it’s somewhat lesser known.


However, Tim, who replied previously, is working on a new version of Scratch which is not only optimised for the Pi but also will incorporate GPIO functionality natively, and he’ll build in features like controlling Minecraft in too. Keep an eye on the blog for updates and see the latest on the scratch tag.

M.O.B. avatar

I’ve used that and it still works well with the built-in Minecraft-Pi. Here is how I installed it:

Here is an example of what you can build using Scratch 1.4 in Raspbian:

Junya Ishihara avatar

I am the author of scratch2mcpi. I am surprised very much by my project being mentioned here.

I am very glad that Minecraft Pi is now pre-installed in Raspbian OS. I have already updated the scratch2mcpi installation script to skip Minecraft Pi installation if it is already installed and have confirmed that it is still working with the pre-installed version.

Although my English may be not fluent, I am very welcome to communicate in English. Please use Github Issues of https://github.com/scratch2mcpi/scratch2mcpi or email me if you have some questions or feature requests about scratch2mcpi.

[email protected]

John Smith avatar

Will you be adding more features, or possibly survival mode? The current form is nice but I could use something more to work with…

Richard Bradley avatar

There is a patched version of minecraft http://www.ledgerlabs.us/raspberrypi/files/minecraft/patches/mcpipatched_survival_binary.zip that brings in a partial survival mode – creates cows, sheep and chickens quickly, and then makes zombies, creepers and spiders. You can then move then about using the entity api, just like you can with the character. However they can kill you but you can’t kill them. When you go back to the normal version the creatures remain. Great for teaching exception handeling
You can also download bless hex editor and open the hidden .minecraft directory in your home directory, tunnel down to and open level.dat and change game type from 01 to 00 and get sort of day/night. Goes from dim to dark and back. Minecraft pi follows, sort of, the format of the Pocket vesion.

Jim Mike avatar

“…but Minecraft is important to us, particularly its use in education, and we’re confident that it won’t be taken from us.”

Please share with us all the reason(s) for your confidence, seeing as how this is MICROSOFT you’re hoping will “…do the right thing”.

“…but Minecraft is important to us…”.

The problem is that “us” is not important to Microsoft.

I think it was Einstein who said that that “Insanity is doing the same thing over and over again, each time expecting different results.”

Ring any bells?

API avatar

With respect, wha’ts in it for MS if they take it away?

For one thing, the Pi version of Minecraft is not the same as the “real” version – it’s a completely different codebase for one thing. It’s ported from an alpha build of the pocket edition.

Given that it’ll only work on ARM systems by discontinuing it all they’d be doing is shouting “Hey, kids – we suck and don’t want to let you learn cool computing skills”.

Microsoft are a sucky company, there’s no doubt about it. But they aren’t THAT stupid. They do a lot of education related projects.

Just be thankful EA didn’t but it out – it’d have DLC already embedded into it by now, along with OriginPi.

markit avatar

Well, what about hurt Free software? What about do an “education version” that works only on M$ Windows / M$ tablets?
As usually, having “free” (as in beer) program hurts the need of develop a free (as in freedom) one, and exposes the adopters not only to spyware or other bad stuff, but also to the will of the owner of the program. And M$ has a bad bad record about “nice programs” bought and shut down for the interest of other, M$ centric, ones.
I really dislike the rpi attitude torwards proprietary programs, that is against education and short signed.

Simon (the Cynic) avatar

From what I have read…
* Minecraft is big on the XBox. An increased use of Minecraft will benefit sales of the XBox.
* The API could easily be changed to .NET from Python. Getting the Minecraft users to write their stuff in .NET will benefit Microsoft programming technologies
* There are a number of Microsoft “chat” technologies that can be implemented in Minecraft
* There are lots of expensive Minecraft servers that could be replaced by Microsoft servers (or their cloud services)

It will be easy for Microsoft to manipulate the Minecraft environment to only work on Microsoft technology. How long will they wait beyond this point before they push XBox Minecraft (offline and in the Cloud) as their programming education tool, and how long after that before their legal team attacks all other uses of Minecraft (the name and the concept).

M.O.B. avatar

I’ve updated how to program the built-in Minecraft-Pi in JavaScript with Java 8 & Nashorn. http://www.raspberrypi.org/forums/viewtopic.php?p=552802#p552802

Jim Mike avatar

“You live and learn. At any rate, you live.”
― Douglas Adams, Mostly Harmless

Olly Clark avatar

We tried to do a Python Minecraft workshop at our CoderDojo yesterday in Blackpool, we were using the latest build of NOOBS on our Pi’s 1.3.10, however when we came to defining the create function mc = minecraft.Minecraft.create() we experienced problems establishing a connection to Minecraft, IDLE gives me the following error:

Traceback (most recent call last):
File “”, line 1, in
mc = minecraft.Minecraft.create()
File “/usr/lib/python2.7/dist-packages/mcpi/minecraft.py”, line 171, in create
return Minecraft(Connection(address, port))
File “/usr/lib/python2.7/dist-packages/mcpi/connection.py”, line 17, in __init__
self.socket.connect((address, port))
File “/usr/lib/python2.7/socket.py”, line 224, in meth
return getattr(self._sock,name)(*args)
error: [Errno 111] Connection refused

Anyone else experiencing a similar problem, or have a work around for it, I’ve been playing around with it today, but I’m not really getting anywhere with it.



Jonathan Fine avatar

Sorry to ask the obvious, but was Minecraft already running? I get the very same error when I run

>>> mcpi.minecraft.Minecraft.create()

on a machine that doesn’t have Minecraft running.

Ben Nuttall avatar

Hi Olly

Can you confirm the Minecraft window was open with the game started? It won’t connect unless you’re in the Minecraft world (otherwise there’s nothing to connect to).


Olly Clark avatar

Thanks for the responses Ben and Jonathan, yes Minecraft Pi Edition v0.11 alpha is running when I execute the mc = minecraft.Minecraft.create() in IDLE



Olly Clark avatar

Resolved it, by creating a new world, not quite sure what happened with that.



Jim Mike avatar

‘Most people regard Bill Gates as a knight in shining armor (sic) riding to the rescue of the PC industry. This [mind-set] conveniently ignores the fact that it was he who, by peddling second-rate technology, got us here in the first place.’

–paraphrase by Douglas Adams

“Never underestimate your own ignorance.” –Albert Einstein

“We are all born ignorant. To remain stupid requires hard work.” –Benjamin Franklin

API avatar

Give it a damn rest with the completely pointless quotes.

Jim Mike avatar

“I would like to take you seriously,‭ ‬but to do so would affront your intelligence.‭”
‬–William F.‭ ‬Buckley,‭ ‬Jr.

markit avatar

What about instead help/collaborate with minetest project, that is GPL, to make it work faster in rpi and provide a python-usable api (I think minetest is wrote in Lua language).
This will save our future and provide the FULL source code for people to hack and study (having the source in Lua is far better that not having it at all). I really dislike the “injection” of proprietary software in RPI, you are repeating the story when proprietary software took over the “do it yourself” and no one cared anymore about programming.
One of the main messages RPI project must pass is “you can only learn from Free software, you can only trust Free software, you can only modify and safely share Free software”.

aberts10 avatar

I agree with you, I did’t have much luck with minetest, but it does sound amazing to be able to make your own mods/modify the world with python code, if only they created a API for python, when they do forget minecaft pi.

Rob avatar

I am trying to do some python programming using the nano editor. In the past, I would “cd mcpi/api” to put my programs here to run. I would run programs from LXTerminal — “python placeblock.py” for example. Now I cannot find this folder. Where do I find it on the new image of Raspbian? Is IDLE my only option for programming?

Wolf avatar

I found that when I started Minecraft pi that there was no sound at all is this supposed to happen? and also, is there going to be an update were we can program mobs in or more elements in?

Peter avatar

Wolf, there is no sound in this edition, though at least one person has written a Python script that can play various sounds as it sees the player performing certain actions. Probably crude, given what it has to work with… but I haven’t looked at it myself. You can google for it.

As for updates, this page http://minecraft.gamepedia.com/Pi_Edition says source availability is “partial”, so that probably means updates are limited to peripheral areas such as external interfaces or mods. I’m new to Minecraft (not to mention the Pi) so I could easily have overlooked some info that refutes that claim…

Comments are closed