Pygame Tutorials
Windows Executables

by Pete Shinners
pete@shinners.org

Revision 1.2, January 28th, 2002



Introduction

One drawback to creating your game with pygame is the large amount of dependencies that your game requires. In order for people to play your game, they need a lot of libraries installed. For unix users, this isn't too bad, since most unix distributions come with their own package and dependency management system. On Windows there is nothing like this, and it is more difficult for a Windows user to just download your python source and run your game.
 
The best solution is to create a collection of all the needed files for your game to run. With python this can mean a lot of files. This document will show you the tools you need to create a standalone version of your game. It is not difficult.
 
 

Download The Tools

The first thing you need to do is download the tools to build the executable. We will use the excellent PY2EXE tool. This package extends the distutils to turn your python code into an executable. You can grab the latest version from the PY2EXE page. It uses a simple windows installer to manage the installation.
 
To use PY2EXE you'll need to create a simple distutils script to run it. I've created a version of this script that I suggest you use. pygame2exe.py.
 
 

Build the Script

There's a small block of variables you will want to change in the pygame2exe.py script to make it work for your specific game. 
project_name = "aliens"         #name for exe
project_script = "aliens.py"    #name of base .PY
icon_file = "aliens.ico"        #name of .ICO
optimize = 2                    #0, 1, or 2; like -O and -OO
dos_console = 0                 #set to 1 to run in a DOS box
data_directories = ['data']     #used data directories
extra_modules = []              #any extra modules that are missing
Most of the options are pretty self descriptive. When first testing your game, you'll want to set the dos_console value to 1. This will print any errors into the dos console. When you release your game, you'll want to set it back to 0, so your game can run without opening a dos prompt.
 
If you notice your game doesn't run, and get an error about missing modules, you can add the names of specific missing modules to the list named extra_modules. For example, if your game uses the surfarray module, surfarray depends on the Numeric modules, but sometimes it can be difficult for PY2EXE to detect Numeric as a dependency. You can add the missing Numeric modules to this list and everything will be ok.
 
Once you are all setup, simply run this script and it will do all the work. The final executable and DLLs will be placed inside a project directory, which will be inside a directory named "dist".
 
You'll notice there aren't any .PY source files in the final directory. That is because all the needed python source has been compressed as bytecode into the actual executable file.
 
The icon_file variable is an optional name of a .ICO file to use for the executable. You can leave it empty ("") and it will be ignored. Also be warned the icon_file doesn't work too well, especially on windows9x.
 
The data_directories is a list of paths that will be copies into the final game directory. Since most games out there will require some sort of graphics/sound/font resources, this will help copy them into the correct place.
 
You'll need to doublecheck that all the game resources and files got copied into the final directory in the "dist" folder. Once that is done and the game is working, you can compress the entire directory into a .ZIP file and send it to all your friends. They do not need any versions of python or SDL installed on their machines. Even if they have older versions of python (like version 1.5.2), it will not interfere with your game.
 
You can also safely pick through the final game directory, and remove any of the "PYD" files that you don't expect your game to use. for example, if you don't use joysticks in your game, you can remove the "joystick.pyd" to make your game size a little smaller.
 
 

Creating an Actual Installer

There's nothing wrong with distributing your game in a .ZIP file. But it is usually a lot nicer to create an installer executable so the game can automatically decompress itself, as well as setup Start Menu icons and adding an option to uninstall. For this you'll need to use one of the many available installing tools for windows. There are many free ones to choose from, and there are several high quality ones.
 
I can recommend INNO Setup for creating the install tool, and ISTool for configuring the package. These are both of the utilities I use when creating the installable pygame package for windows.