Getting Started with Pygame

What Is Pygame, and Getting It Installed

Pygame is a free, open-source Python library built on top of SDL (Simple DirectMedia Layer) that gives you everything a 2D game needs: a window to draw in, image and sound loading, keyboard/mouse/controller input, collision helpers, and drawing primitives. It's been the go-to library for learning game development in Python for over two decades because it's simple to install, well-documented, and lets you see results in minutes rather than hours.

If you haven't already, install it with pip from your terminal. Then confirm the install worked by importing pygame in a new file — if no error appears, you're ready to build.

pip install pygame

import pygame
print(pygame.ver)   # prints the installed Pygame version, e.g. "2.6.0"

Initializing Pygame and Creating the Window

Before you can use any Pygame feature, you must call pygame.init() — this starts up all of Pygame's internal modules (display, sound, fonts, etc.) in one call. Next, pygame.display.set_mode((width, height)) opens the game window and returns a Surface object — think of a Surface as a rectangular canvas of pixels you can draw on. This particular Surface is special: it's the display surface, the one that actually gets shown on screen. You can also set the text in the window's title bar with pygame.display.set_caption().

import pygame

pygame.init()                                  # start up all Pygame modules

WIDTH, HEIGHT = 800, 600
screen = pygame.display.set_mode((WIDTH, HEIGHT))   # the display surface
pygame.display.set_caption("My First Pygame Window")

The Game Loop, Clock, and Frame Rate

A window that opens and instantly closes isn't a game — you need a loop that keeps the window alive and redraws it continuously. This is the game loop: a while loop that runs until the player quits. Left unchecked, this loop would run as fast as your CPU possibly can — hundreds or thousands of times a second, wasting power and running inconsistently across different machines. That's why every Pygame loop uses a pygame.time.Clock() object and calls clock.tick(60) once per frame: this caps the loop at a steady frame rate (60 frames per second is standard) and makes movement speed consistent regardless of hardware.

Handling Events and Closing the Window Properly

Pygame reports everything that happens — key presses, mouse clicks, window close requests — as events, delivered through pygame.event.get(). This returns a list of every event that occurred since the last time you checked, and you loop through them each frame. The most critical event to handle is pygame.QUIT, fired when the player clicks the window's close button — if you don't listen for it, your window will freeze and become unresponsive (unkillable except by force-quitting the process).

To close the window properly, catch that QUIT event, flip a running flag to False so the loop exits, and then call pygame.quit() after the loop ends to clean up Pygame's internal resources before the script finishes.

for event in pygame.event.get():
    if event.type == pygame.QUIT:
        running = False
    if event.type == pygame.KEYDOWN:
        if event.key == pygame.K_ESCAPE:
            running = False

Your First Interactive Program: The Complete Loop

Now let's assemble everything from this module into one complete, correct, runnable program. This is the minimal skeleton you will copy at the start of nearly every project in this course: initialize Pygame, open a window, create a clock, run the loop (handle events → update → draw → tick), and quit cleanly when the window closes.

import pygame

# --- Setup ---
pygame.init()
WIDTH, HEIGHT = 800, 600
screen = pygame.display.set_mode((WIDTH, HEIGHT))
pygame.display.set_caption("First Interactive Program")
clock = pygame.time.Clock()

running = True

# --- Game loop ---
while running:
    # 1. Handle events
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False

    # 2. Update game state (nothing to update yet)

    # 3. Draw everything
    screen.fill((15, 20, 40))          # clear the screen with a dark blue
    pygame.draw.circle(screen, (52, 211, 153), (WIDTH // 2, HEIGHT // 2), 40)
    pygame.display.update()             # push the new frame to the window

    # 4. Cap the frame rate
    clock.tick(60)

# --- Clean shutdown ---
pygame.quit()

Mini Project: A Window That Reacts to Keypresses

Let's make the window slightly interactive by combining events with drawing — pressing the spacebar changes the background color. This mini project ties together everything you've learned: initialization, the display surface, the game loop, clock, events, and clean shutdown.

import pygame

pygame.init()
screen = pygame.display.set_mode((800, 600))
pygame.display.set_caption("Mini Project: Color Switcher")
clock = pygame.time.Clock()

bg_color = (15, 20, 40)
running = True

while running:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False
        if event.type == pygame.KEYDOWN and event.key == pygame.K_SPACE:
            bg_color = (5, 150, 105) if bg_color == (15, 20, 40) else (15, 20, 40)

    screen.fill(bg_color)
    pygame.display.update()
    clock.tick(60)

pygame.quit()

The Loop as a Cycle, Not a Straight Line

pygame.init() only ever runs once, right at the start. Everything after it — handling events, updating state, and drawing the frame — repeats endlessly in a cycle until running becomes False. Seeing it as a loop, rather than a list of four steps, makes it obvious why the game "does the same thing" every single frame.