Load Images in Pygame: image.load() and convert_alpha()

pygame.image.load() reads an image file and returns a Surface. Load images once, before the game loop, and blit them every frame:

import pygame

pygame.init()
screen = pygame.display.set_mode((480, 320))
clock = pygame.time.Clock()

player = pygame.image.load("assets/images/player.png").convert_alpha()
chest = pygame.image.load("assets/images/chest.png").convert_alpha()
player_rect = player.get_rect(midbottom=(120, 260))
chest_rect = chest.get_rect(midbottom=(360, 260))
print(player.get_size())

running = True
while running:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False

    screen.fill((110, 180, 235))
    pygame.draw.rect(screen, (90, 160, 80), (0, 260, 480, 60))
    screen.blit(player, player_rect)
    screen.blit(chest, chest_rect)
    pygame.display.flip()
    clock.tick(60)

pygame.quit()

(48, 48)

The examples on this page use the free art pack in an assets folder (images by Kenney, CC0). On your own computer, put your PNG files in a folder next to your script and change the paths.

convert() and convert_alpha()

A freshly loaded image is stored in the file's pixel format. Converting it to the screen's format makes every blit several times faster:

Both need the window, so they must come after pygame.display.set_mode(). Called before it, they fail with pygame.error: No video mode has been set.

Placing an image: get_rect()

image.get_rect() returns a Rect the size of the image. Keyword arguments place it by any point:

rect = image.get_rect(center=(240, 160))
rect = image.get_rect(midbottom=(100, 260))   # standing on a floor at y=260
rect = image.get_rect(topright=(470, 10))

Keep that Rect as the object's position, move it, and blit the image at it.

A tiled background

Small tiles repeated across the screen make a background from one image. Two loops place a copy every tile width:

import pygame

pygame.init()
screen = pygame.display.set_mode((480, 336))
clock = pygame.time.Clock()

floor = pygame.image.load("assets/images/floor.png").convert()
size = floor.get_width()

background = pygame.Surface(screen.get_size())
for y in range(0, 336, size):
    for x in range(0, 480, size):
        background.blit(floor, (x, y))

knight = pygame.image.load("assets/images/knight.png").convert_alpha()
rect = knight.get_rect(center=(240, 168))

running = True
while running:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False

    keys = pygame.key.get_pressed()
    rect.x += (keys[pygame.K_RIGHT] - keys[pygame.K_LEFT]) * 4
    rect.y += (keys[pygame.K_DOWN] - keys[pygame.K_UP]) * 4
    rect.clamp_ip(screen.get_rect())

    screen.blit(background, (0, 0))
    screen.blit(knight, rect)
    pygame.display.flip()
    clock.tick(60)

pygame.quit()

The tiles are blitted once onto a background Surface before the loop, so each frame costs one blit for the whole floor. Press Play, click the game and walk with the arrow keys.

File not found

FileNotFoundError: No file 'player.png' found in working directory '/Users/sam'.

A relative path such as "player.png" is looked up from the working directory, the folder your terminal or editor ran Python from, which is often not your script's folder. Two fixes:

import os

HERE = os.path.dirname(os.path.abspath(__file__))
player = pygame.image.load(os.path.join(HERE, "images", "player.png")).convert_alpha()

or run the game from its own folder (cd mygame, then python main.py). Also check the name's capitals: Player.PNG and player.png are different files on macOS and Linux servers.

Formats

Pygame loads PNG, JPG, BMP, GIF (first frame only), TGA, WebP and more. Use PNG for game art: it keeps sharp edges and transparency. To save a Surface, for example a screenshot, use pygame.image.save(screen, "shot.png").

Next: scale, rotate and flip images, then turn them into sprites.