Loading video player…

Background and Setup

What is PyGame and where did it come from? In this lesson, you’ll explore some of the background of pygame and how to set it up on your system.

pygame is a Python wrapper for the SDL library, which stands for Simple DirectMedia Layer. SDL provides cross-platform access to your system’s underlying multimedia hardware components, such as sound, video, mouse, keyboard, and joystick.

pygame started life as a replacement for the stalled PySDL project. The cross-platform nature of both SDL and pygame means you can write games and rich multimedia Python programs for every platform that supports them!

For this tutorial, the demonstrations shown will be done on a Macintosh computer, and the Python environment is setup with a virtual environment. To create a virtual environment on macOS or Windows and activate it, you would use these commands from your terminal:

$ mkdir PyGame
$ cd PyGame

$ python3 -m venv game_env

$ # macOS virtual environment activation
$ source game_env/bin/activate

$ # Windows virtual environment activation
$ game_env/Scripts/activate

To install pygame into your virtual environment or your platform, use the pip command:

(game_env) $ python3 -m pip install pygame

You can verify the install by loading one of the examples that comes with the library:

(game_env) $ python3 -m pygame.examples.aliens

If a game window appears, then pygame is installed properly! If you run into problems, then the GettingStarted guide outlines some known issues and caveats for all platforms.

00:00 In this lesson, I’ll give you a bit of background about PyGame and how to set it up on your machine. So, what is PyGame? Where did it come from? PyGame is a wrapper for the SDL library.

00:11 SDL stands for Simple DirectMedia Layer, and it provides cross-platform access to your system’s underlying multimedia hardware components. These are things like your sound, video, mouse, keyboard, and joystick—if you have one.

00:26 This cross-platform nature of both SDL and PyGame means that you can write games and rich multimedia Python programs for every platform that supports them.

00:36 So, how do you install it? Like many other tools that you may have added to your Python environment, you can install it using pip. I’m going to create a virtual environment, which I’ll show you as I go through these steps, and then use pip install to add it to that environment. But basically, you can use the standard pip install and in this case, the library is pygame. After that, I’ll take you through verifying the installation where I’m going to have you try one of the examples that comes with the pygame library. For this series, I’m creating a virtual environment. The creation of virtual environments varies depending on the platform you’re working on. I’m using a Mac, so these will be the steps for creating a virtual environment on a Mac system, but I’ll include links to resources on Real Python to learn more about creating virtual environments. And it’s not a requirement; it allows me to keep a separate clean environment for the different types of projects that I might want to explore.

01:31 I’m going to use the command venv and then give it the name of the environment I want to create, which is going to be game_env. Then I need to activate it.

01:44 You can see with the parentheses there, that now I’m inside the game_env. If I were to type python you can see that I’m running a version of Python—Python 3.7.2.

01:52 So from here, I can use the install command…

02:00 to install pygame. Now to try out that example…

02:10 it’s pygame.examples.aliens.

02:21 The Spacebar… is your fire button, and you can see it’s working just fine. Okay. Looks good! For the next lesson, you’ll get a chance to build your first basic PyGame program.

Avatar image for mikesult

mikesult on May 1, 2020

Hi Christopher,

I ran into an error trying to install pygame For context: I’m on a macbook pro. I was able to setup the venv and when I entered ‘python’ to check the version it returned “Python 3.8.2 …’

Then after I activated the virtual env I tried to install pygame with

python3 -m pip install pygame

I received a very long error message (over 200 lines) which I didn’t understand but around line 212 of the error message I did see this part which seems like it could be the source of the problem

” In file included from src_c/pygame.h:32: src_c/_pygame.h:216:10: fatal error: ‘SDL.h’ file not found #include <SDL.h> “

Any ideas as to how to solve this problem?

I know that in the past I’ve run some pygame examples I’ve found on the internet but it wasn’t in a venv.

BTW, I’m enjoying the Real Python podcast you are hosting.

Mike Sult

Avatar image for Chris Bailey

Chris Bailey RP Team on May 1, 2020

Hi @mikesult,

I have seen that myself sometimes, it seems to be a problem with using the virtual environment. This is the simplest route. If you are okay with foregoing the virtual environment for this, you could install pygame to your primary Python install. So without a virtual environment activated you would type python3 -m pip install pygame.

This would allow you to use it for other future game projects also. If you no longer need to use it you could later python3 -m pip uninstall pygame from your main Python setup.

If that does not work then it has to do with SDL not being installed, which is a bit more work. I hope this helps. I will look at if I should remove the suggestion for using the virtual environment in the text below the lesson.

Notes about it here, Getting Started with Pygame

Avatar image for mikesult

mikesult on May 3, 2020

Hi Chris,

I received the same error when trying to install without the venv. I think I have a conflict with two versions of python. I have both an anaconda installation of 3.7.3 and a regular installation of 3.8.2 As a hobbiest, (sh) it happens. I still have some problem but it is an interesting adventure trying to figure out the problem.

the short story: The 3.8 version was missing the SDL library.

stackoverflow had some of the solution:


(the long story is a little too long so I’ll omit it but I think I can continue on now.)

Avatar image for shevachp

shevachp on July 19, 2020

Hi Chris, I unfortunately just moved over from a mac to Windows and I’m having problems installing pip (to be able to install pygame). I downloaded “get-pip” and when I try to run it, it flashes on the screen for a second and then it disappears. After trying over and over again I tried to install the bash shell on Windows 10 (I figured maybe the problem is the terminal that I was using). And guess what, the same problem; After I activated it, when I try to run it it flashes on the screen for much less than a second and then disappaers. Do you have any idea what the problem is? Thanks for the help. p.s. I was a little bit past half way in your tutorial when my mac died and your tutorial was very nice and clear and I am really looking forward to finishing it.

Avatar image for Ricky White

Ricky White RP Team on July 20, 2020

Hi shevachp

The Windows version of Python comes with pip included. So you shouldn’t need to install it. What do you see when you run pip --version?

Avatar image for shevachp

shevachp on July 20, 2020

Your a magician. It works now. Thanks a lot

Become a Member to join the conversation.