How to Fix The Pygame Error While Learning Game Development with Python?

I’ve always been fascinated by how games work behind the scenes, so I decided to dive into game development using Python and the Pygame library. I expected a smooth ride, but as with most programming journeys, I hit a few bumps early on. This blog is about how I tackled one of my first real errors in Pygame, what I learned from it, and how I improved my little game project along the way.

Original Code

bif = "main_background.jpg"
mif = "player_head.png"

import pygame, sys
from pygame.locals import *  # 🔴 Error source

pygame.init()
screen = pygame.display.set_mode((640, 360), 0, 64)

background = pygame.image.load(bif).convert()
mouse_c = pygame.image.load(mif).convert_alpha()

while True:
    for event in pygame.event.get():
        if event.type == QUIT:
            pygame.quit()
            sys.exit()

    screen.blit(background, (0, 0))

    x, y = pygame.mouse.get_pos()
    x -= mouse_c.get_width() / 2
    y -= mouse_c.get_height() / 2

    screen.blir(mouse_c, (x, y))  # 🔴 Typo: should be 'blit'

    pygame.display.update()

Error Explain

ImportError: No module named locals

• Cause: I accidentally saved my script as pygame.py. This was a huge mistake because it overrode the real Pygame library, causing Python to import my own file instead. That’s why pygame.locals wasn’t found.
• Fix: I renamed the file to something like game_dev_intro.py and deleted the autogenerated pygame.pyc file to fully remove the conflict. Instantly, that fixed the import issue!

Typo in Method Call

• Issue: I misspelled blit as blir.
• Fix: A simple typo, but enough to crash the program. Once I corrected screen.blir(...) to screen.blit(...), the image displayed properly.

Correct Code

After solving the errors, I decided to improve my program a bit by adding more functionality for practice and learning.

pygame
import sys

# Initialize Pygame
pygame.init()

# Load assets
background_img = "main_background.jpg"
player_img = "player_head.png"

screen = pygame.display.set_mode((640, 360))
pygame.display.set_caption("Simple Mouse Tracker Game")

# Load and convert images
background = pygame.image.load(background_img).convert()
player = pygame.image.load(player_img).convert_alpha()

# Clock for controlling frame rate
clock = pygame.time.Clock()

# Main loop
while True:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            pygame.quit()
            sys.exit()

    # Draw background
    screen.blit(background, (0, 0))

    # Get mouse position and center the player image
    x, y = pygame.mouse.get_pos()
    x -= player.get_width() // 2
    y -= player.get_height() // 2
    screen.blit(player, (x, y))

    # Draw a simple red circle at the cursor location
    pygame.draw.circle(screen, (255, 0, 0), (x + player.get_width() // 2, y + player.get_height() // 2), 5)

    # Print mouse coordinates in console
    print(f"Mouse Position: ({x}, {y})", end="\r")

    # Update screen and control FPS
    pygame.display.update()
    clock.tick(60)

Practice Feature I Added

After fixing the core issue, I added these features to get more comfortable with Pygame:

• Frame Rate Limiting using clock.tick(60) to keep my game smooth.
• Mouse Tracker that keeps the image centered under the cursor.
• Red Circle Cursor drawn with pygame.draw.circle for more interactivity.
• Live Mouse Coordinates printing to the console, just for debugging fun.
• Custom Game Window Title with pygame.display.set_caption().

Final Thought

This was my first hands-on experience with a real game loop, and it taught me a lot about both programming and debugging. One of the biggest lessons I learned is that file naming in Python is extremely important never name your script the same as the library you’re trying to import, like I mistakenly did with pygame.py.

I also realized how even the smallest typos, like a misspelled function name, can break your entire program. These may seem like minor mistakes, but they have a big impact, especially when you’re just starting out. Despite the simplicity of the project, solving my first Pygame error felt incredibly empowering.