Learn to Program with Minecraft: Troubleshooting Guide

The book Learn to Program with Minecraft requires Minecraft 1.8 or 1.9, Python 3.5 or newer and Java 7 or newer.

If you're having difficulty getting your environment set up, software versioning is the most likely problem. Follow the instructions on this page to check that you are using the correct versions of Minecraft, Python, and Java.

If you've confirmed that you have the correct versions and you're getting other errors, refer to the later sections in this document (linked below).

Choosing a Minecraft Version
Is Python installed?
Is Java installed?
I Want to Use Python 2 and Python 3!
Start_Server, File Cannot Be Found (Windows)
Connection Refused Error (For Mac)
Nothing Happens After I Click on Install_API (For Windows)
Permissions Error (For Mac)
I Get a Different Error!

If that doesn't work, drop us a line at [email protected]. Please include your operating system and version, the versions of Python and Java that you have installed, and any specific error messages.

Choosing a Minecraft Version

Purchase the standard Minecraft version from minecraft.net to follow along with the book.

Please know that Minecraft Windows 10 Edition, Minecraft for Xbox, Minecraft: Education Edition, and Minecraft: Pocket Edition are not compatible with the book.

In order to use your Spigot server, your Minecraft version needs to match the Spigot version exactly. But new versions of Minecraft come out all the time, so if you update Minecraft, Spigot won’t work with the new version anymore. In order to make your Spigot and Minecraft versions match, you can set up a profile.

When you set up a profile, you tell Minecraft that you only want to use the version of the game that will work with the version of the server that you are using. In other words, a profile allows you to continue using the same server even when newer versions of Minecraft are released.

Once you set up a profile, you should be able to use our book’s coding directions and you'll know one more of Minecraft’s secrets, and will be further along on your journey to become a Minecraft Master!

You can see it in action in this handy guide from HowToGeek:

Let’s get started.

For Windows

Before you create your profile, you need to find out which version of the server you are using. Follow these steps to do that:

Step 1. In the Minecraft Tools folder, open the Start_Server file. A window will appear and begin to set up the server.
Step 2. Once the setup is finished, scroll to the top of the text in the window.
Step 3. Near the top (around the third or fourth line), you should see text saying Starting minecraft server version x.x.x.
Step 4. Make a note of the version number shown on your screen.

Now that you know which server version you are using, you can set up the game profile with these steps:

Step 1. Open the Minecraft launcher but do not click Start Game quite yet (make sure you leave the server window open when you do this).
Step 2. At the top-right of the Minecraft launcher, click the menu button (which looks like three lines), then click the Launch Options button. This will open the Profile Editor tab.
Step 3. Click the Add New button to create a new configuration.
Step 4. In the Name field, type Learn to Program with Minecraft.
Step 5. In the Version section, use the drop-down menu to select the version of the server that you’re using. For example, in Figure 1-5, I’m using version 1.9.2.
Step 6. Click the Save button. Your profile has now been set up.

From now on, every time you want to use Minecraft with this book, select the Learn to Program with Minecraft profile in the drop-down menu in the bottom-left corner of the Minecraft launcher.

You can swap back to the latest version of Minecraft at any time by selecting the (default) option in the drop-down menu.

For Mac

Before you create your profile, you need to find out which version of the server that you are using. Follow these steps to do that now:

Step 1. In the Minecraft Tools folder, open the Start_Server file. A window will appear and will begin to set up the server.
Step 2. Once the setup is finished, scroll to the top of the text in the window.
Step 3. Near the top (around the third or fourth line), you should see text saying Starting minecraft server version x.x.x.
Step 4. Make a note of the version number shown on your screen.

Now that you know which server version you’re using, you can set up the game profile with these steps:

Step 1. Open the Minecraft launcher but do not click Start Game.
Step 2. In the top-right corner of the Minecraft launcher, click the Menu button (which looks like three lines), then click the Launch Options tab. This will open the Profile Editor tab. Click the Add New option.
Step 3. In the Name field, type Learn to Program with Minecraft.
Step 4. In the Version field, use the drop-down menu to select the version of the server that you’re using. For example, in Figure 1-15, I’m using version 1.9.
Step 5. Click the Save button. Your profile has now been set up.

From now on, every time you want to use Minecraft with this book, select the Learn to Program with Minecraft profile in the drop-down menu in the bottom-left corner of the Minecraft launcher.

You can swap back to the latest version of Minecraft at any time by selecting the (default) option in the drop-down menu.

Is Python Installed?

Follow these steps to make sure you're running Python 3.5.0 or newer.

Note: If you find that you have both Python 2 and Python 3 installed, you should uninstall Python 2—or follow the instructions in “I Want to Use Python 2 and Python 3!” below.

For Windows

You should be able to see all the installed programs in the Windows Start menu, including Python. The simplest way to confirm you've gotten the right version of Python is to go to the Start menu, then choose All Programs or Programs. You can also search for "Python" to determine which Python version is installed. The Python version number might be part of the name that shows up in the Start menu; if not, open IDLE and the version number will be displayed in the shell.

If it's anything older than 3.5.0, you'll need to install the updated version. Follow the steps in Chapter 1 to install Python version 3.5.0.

For Mac

Step 1. Open Finder and search for Terminal. Click Terminal to open it.
Step 2. At the Terminal prompt, type Python -V (note that the V is uppercase) and press RETURN.
Step 3. You will see the Python version number--if it's anything older than 3.5.0, you'll need to install an updated version. Follow the steps in Chapter 1 to install Python version 3.5.0.

Is Java Installed?

Follow these steps to make sure you're running Java 7 or newer.

For Windows

You should be able to see all the installed programs in the Windows Start menu, including Java. The simplest way determine which version you have installed is to do the following:
Step 1. Go to the Start menu.
Step 2. Choose All Programs.
Step 3. Find the Java folder and click About Java.

You can also test the version of Java by using this method:
Step 1. Open the Start menu, search for cmd, and open the command prompt.
Step 2. Run the command java -version. You will see a message that says something like java version "1.8.0_72". The version of Java that you are using is the number after the first dot, which is version 8 in our example message. If your version is older than 7 (or if Java isn’t installed at all!), you’ll need to update or install Java. To do so, follow the installation instructions in Chapter 1.

For Mac

Step 1. Open Finder and search for Terminal. Click Terminal to open it.
Step 2. At the Terminal prompt, type java -version and press RETURN.
Step 3. You will see a message that says something like java version "1.8.0_72". The version of Java that you are using is the number after the first dot, in this case version 8. If your version is older than 7, you'll need to update Java. To do so, follow the installation instructions in Chapter 1.

I Want to Use Python 2 and Python 3!

If you want to have both Python 3 and an older version of Python installed, you need to modify the Install_API file to specify that it should use Python 3, rather than the older version.

The Minecraft Python API will work with older versions of Python, but you must use Python 3 if you want to run all the code examples from the book—otherwise you'll get an error if you try to use the print() function and a few other Python things. But you can still keep another, older version of Python on your computer if you want to.

Once you've installed the API, you'll need to make sure that you use the correct version of IDLE. Make sure you use IDLE 3 when writing and running code—otherwise the programs from the book will not work.

For Windows

To modify the Install_API file, follow these steps:

Step 1. Open the Minecraft Tools folder and find the Install_API file.
Step 2. Right-click the Install_API file and select Edit.
Step 3. Once the file opens, find the line that begins with this:

python -m pip install minecraftPythonAPI.zip

Step 4. Edit the line by changing python to python3 so that the line looks like this:

py -3 -m pip install minecraftPythonAPI.zip

Step 5. Save the file and close it.
Step 6. Double-click the Install_API file to install the Minecraft Python API.

For Mac

To modify the Install_API file, follow these steps:

Step 1. Open the Minecraft Tools folder and find the Install_API file.
Step 2. Control-click the Install_API file and select Edit.
Step 3. Once the file opens, find the line that begins with this:

python -m pip install minecraftPythonAPI.zip

Step 4. If you can’t find that line, then you already have the new file and don’t need to do anything else. Otherwise, edit the line by changing python to python3 so that the line looks like this:
python3 -m pip install minecraftPythonAPI.zip

Step 5. Save the file and close it.
Step 6. Double-click the Install_API file to install the Minecraft Python API.

Start_Server, File Cannot Be Found (Windows)

When you click on the Start_Server file you might see a window saying “Windows cannot find 'C:\Users\Frank\Documents'”or something similar.

To work around this issue, open the server folder and double click on the start.bat file. The server should start normally. Every time you need to start the server in the future repeat these steps.

Alternatively, download the latest version of the book's setup files, Minecraft Tools, linked on the book's catalog page.

Connection Refused! (For Mac)

In Python, after typing the line mc = Minecraft.create(), you might get an error message that says

ConnectionRefusedError: [Errno 61] Connection refused

or a similar error that says

ConnectionRefusedError: [Errno 10061] No connection could be made because the target machine actively refused it.

This error is most frequently caused by an out-of-date version of Java installed on your computer. In order to fix this issue, follow the Java installation instructions in Chapter 1.

If you still get this error after reinstalling Java, your Mac might be using an old version of Java only on the command line. To fix this issue, do the following:

Step 1. Click the search icon on the top-right corner of your screen.
Step 2. In the search box, enter Java Preferences.
Step 3. When the preferences box opens, make sure that only the Java 8 checkbox is ticked.

After you have changed these preferences, the problem should be resolved. However, if you still have this issue, uninstall older versions of Java and then reinstall Java 8.

Nothing Happens After I Click on Install_API (For Windows)

When you run the Install_API file during step 5 of “Installing the Minecraft Python API and Spigot” (page 6), you might see a black window pop up.

If you see a window like this, you might be experiencing a bug with pip, which is used to install the API. To work around this, you need to install the Minecraft Python API via the command line. Follow these steps:

Step 1. Open the Minecraft Tools folder. You should see the minecraftPythonAPI.zip file.
Step 2. In the file browser, click the address bar to highlight it, then copy the text (right-click and select Copy, or press CTRL-C). The address should look something like this:

C:\Users\user\Minecraft Python\Minecraft Tools

Step 3. Click the Start menu and search for PowerShell. Click PowerShell to open it.
Step 4. At the PowerShell prompt, type cd and then right-click to paste the address of your Minecraft Tools folder.
Step 5. Add single quotation marks around the text you just pasted. The line should look something like this:

cd 'C:\Users\user\Minecraft Python\Minecraft Tools'

Step 6. Press ENTER. Now you can run commands in PowerShell using the contents of the Minecraft Tools folder.
Step 7. On the next line, type the following command to install the API:

python -m pip install minecraftPythonAPI.zip

Step 8. Press ENTER. The Python API should now be installed correctly.

Permissions Error (For Mac)

During step 8 of “Installing the Minecraft Python API and Spigot” (page 15 or 16), you might get this error:

The directory '/Users/YourUserName/Library/Caches/pip/http' or its parent
directory is not owned by the current user and the cache has been
disabled. Please check the permissions and owner of that directory. If
executing pip with sudo, you may want sudo's -H flag.

Check all the folders that the Install_API file is inside of and remove any spaces from the folder names. To do this, follow these steps:

Step 1. Control-click the icon of the folder with a space in the name.
Step 2. From the pop-up menu, select Rename, then remove the space from the folder’s name. Note that you should not have to do this with the hard drive itself (Macintosh HD)!

Once you have done this, try running the Install_API file again.
On some Macs, you might still get an error—however, the API has still installed correctly. If you see the following line, the API has installed correctly and you can ignore the error message:

Requirement already satisfied (use -–upgrade to upgrade): py3minepi...

I Got a Different Error!

If you get an error that isn't listed on this page, contact us at [email protected]. Please include information about your operating system, the versions of Minecraft, Python, and Java that you are using, and any specific error messages you've received.