Hey everybody! Today I thought I'd share a bit of knowledge that might help my fellow fledgling game devs, particularly those who, like me, mainly use Python and Pygame when making their games. I'm going to show you how to make a nice and tidy Windows executable out of your python script using PyInstaller! That means that you can distribute your game to anyone with a Windows machine and they can play it, whether they have the Python interpreter and Pygame installed or not.
This tutorial assumes you know enough Python and Pygame to make a simple script. If you don't know Python, their docs are excellent, and there is a tutorial on the official website. If you don't know Pygame, I recommend starting with creator Pete Shinners' Line by Line Chimp Example. You can of course go further than that with Pygame, but I believe that the Chimp tutorial and a knowledge of basic Python syntax will be sufficient for you to understand the script I'm going to put up.
Installation
Installation is actually one of the biggest parts of this tutorial, so I've gone into a lot of detail.
By the way, the rest of the tutorial assumes that you know a little bit about how to work with the Windows command line, and that you already have Python and Pygame installed. Also, I'm using Python version 2.7.5 (rather than the more recent Python 3.x versions). Any version of Python 2.x should be okay, though (Not so sure about 3.x, since I don't use it). Also, I'm using a 32-bit install of Python, so my versions of Pygame and pip-Win will match accordingly.
To begin with, you're going to need to install two programs, namely pip-Win and PyInstaller. The first, pip-Win, is a small package manager that makes it very easy to install PyInstaller and its dependencies. Go to the pip-Win site and download the latest version. When it's done, install the program and run it. It should set itself up, then bring you to a dialog box that looks like this:
 |
| pip-Win's interface. |
* NOTE: If pip-Win is giving you trouble, particularly if it's saying that it fails to install setuptools, you can go and manually download the files ez_setup.py and get-pip.py from the bootstrap.pypa.io site, and place them in the folder that pip-Win is searching (probably "C:\Users\[USERNAME]\Appdata\Local\Temp\). Hopefully it won't cause you this problem, but it did for me on one of my machines, and this is the workaround I found :)
In the field labeled "Command," clear what's there and type in:
pip install pyinstaller==3.0
 |
| Like so |
Then click "Run." If all is as it should be, PyInstaller will install itself. Note: I recommend installing version 3.0 of PyInstaller because I've had some issues with the most recent release of the program. Additionally, to make sure your environment is the same as mine (and you thus hopefully get the same results as me), I suggest entering the following line into pip-Win:
pip uninstall setuptools
Input "y" when prompted and hit enter. When setuptools finishes uninstalling, enter this command in pip-Win:
pip install setuptools==19.2
This should remove a troublesome error wherein an executable created with PyInstaller will not run once compiled.
Once that all is done, we should test if PyInstaller actually installed properly. Open a command window anywhere, such as your desktop (Shift+Right Click and click on "Open command window here").
Now, it's time for a little cmd.exe work. First, we need to edit the PATH environment variable to be able to actually find PyInstaller. You could edit the path to remember this permanently, but I'm always too lazy for that, so what I do is simply make a temporary addendum to the PATH variable. Type this into the command window:
PATH=%PATH%;[Path to your Python folder]\Scripts\
Where [Path to your Python folder] is just what it says; the path to the folder where your Python interpreter is. So, in my case, I would enter:
PATH=%PATH%;E:\Python27\Scripts\
 |
| Showing the PATH, We see that the directory we specified has been added to the end. |
Now, type in:
pyinstaller --version
 |
| You should see something like this. |
It should spit out the version of PyInstaller you have installed (3.0). If so, hooray! Installation is complete, and we can move on to what you actually came here for: making an executable! Don't close this window though, we'll need it in a moment!
Creating the Executable
The first step to creating an executable for your game is making a game! Well, We won't make a whole game here, more like an extremely simple script. Copy the following to your clipboard:
#!/usr/bin/env python
import pygame
pygame.init()
screen = pygame.display.set_mode((200, 200))
frames = pygame.time.Clock()
square = pygame.Surface((32, 32))
square.fill((255, 0, 0))
rect = square.get_rect()
on = True
while on:
frames.tick(30)
for event in pygame.event.get():
if event.type == pygame.QUIT:
on = False
rect.center = pygame.mouse.get_pos()
screen.fill((0, 0, 0))
screen.blit(square, rect)
pygame.display.update()
pygame.quit()
This is an extremely simple "game" that makes a small black screen with a red square on it that will follow your mouse. Make a folder on your desktop (or anywhere, really, but I'm going to assume you made it on your desktop) called "game" and save the above script in that folder as "game.py"
Now, hopefully you took my advice above and didn't close the command window you had open (if you did, that's okay, just open a new one and re-enter the command about the PATH variable). In the command window, type in the following (assuming you are not in the "game" folder already):
cd [Path to your desktop]\game\
Where [Path to your desktop] is the complete path to your desktop directory. For instance, mine would be:
cd C:\Users\HellaMagellan\Desktop\game\
 |
| As you can see, I used a shortcut here, 'cause I'm a certified, Hogwarts-graduate wizard. |
Now, its time to make that executable! A quick word about PyInstaller: there are lots of options you can use when making your executable, all of which are listed at this page. We're going to be making a simple one-file, no-console (windowed) executable. There are many variations, though, so I encourage you to read the PyInstaller docs and experiment!
Now onto the show! Enter this in the command window:
pyinstaller -F -w game.py
You will then see a bunch of text scroll by on the command window. When it's done, look in the newly-created "dist" folder in the "game" directory. Double-click the executable in there - it's your game!
That should about do it for this tutorial. The methods described above can be expanded on by studying through the PyInstaller docs. Here are a few things to keep in mind when using PyInstaller for your Pygame games:
0. If your game makes use of any external resources (images, sounds, etc.), remember to include them with your executable, in the same place your script would look for them! (e.g. if you have an "img" folder that holds all your images, the executable will still need that folder to display the images
1. It is quite easy to create a custom icon for a PyInstaller executable. Simply add the -i option, followed by a path (with no spaces) to a Windows .ico file. I was going to demonstrate how to do that in this tutorial, but I wasn't able to upload an image, 'cuz Blogger turns my .ico's into .png's :P
2. PyInstaller does not like the default font from the pygame.font module (the one that gets used when you pass None to the font argument, as mentioned here). It won't compile a program that makes use of it! You are best off to make use of a specific system font, or, better yet, ship a font file with your game and use that.
3. PyInstaller and setuptools may fix the issues that seem to be going on in the near future. When I first used PyInstaller about 6 months ago, it was much simpler to get it to just work :P
That about does it! Hopefully this tutorial will be useful to someone out there. As always, I'd love to hear from my readers in the comments. Let me know if you liked this and want me to do more tutorials!
So long!
P.S. Next time, I'll have some info about my upcoming #1GAM game! ;)
