Pygame Text: Render Text on the Screen

Pygame does not draw text directly. You render the text with a font, which gives you a Surface, and then blit that Surface like any image:

import pygame

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

title_font = pygame.font.Font(None, 64)
small_font = pygame.font.Font(None, 28)
title = title_font.render("Space Rescue", True, (255, 220, 90))
hint = small_font.render("Press Space to start", True, (200, 200, 220))

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

    screen.fill((16, 18, 40))
    screen.blit(title, title.get_rect(center=(240, 130)))
    screen.blit(hint, hint.get_rect(center=(240, 200)))
    pygame.display.flip()
    clock.tick(60)

pygame.quit()

The three steps

1. Make a font once, before the loop: pygame.font.Font(None, 36). None means pygame's built-in font; 36 is the size in pixels. Pygame fonts covers system fonts and font files.
2. Render: font.render(text, antialias, color, background=None) returns a Surface with the text on it. antialias=True smooths the edges.
3. Blit that Surface at a position or a Rect.

text.get_rect(center=(x, y)) centers it; get_rect(topright=(470, 10)) puts it in the corner, and so on.

A changing score

Text that changes, such as a score, is rendered again when it changes. Rendering is slower than blitting, so a common pattern is to render only when the value is different:

import pygame

pygame.init()
screen = pygame.display.set_mode((480, 240))
clock = pygame.time.Clock()
font = pygame.font.Font(None, 48)

score = 0
shown_score = None
label = None
running = True

while running:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False
        elif event.type == pygame.KEYDOWN and event.key == pygame.K_SPACE:
            score += 10

    if score != shown_score:
        label = font.render(f"Score: {score}", True, (255, 255, 255))
        shown_score = score

    screen.fill((30, 90, 60))
    screen.blit(label, (20, 20))
    pygame.display.flip()
    clock.tick(60)

pygame.quit()

Press Play, click the game and press Space to add points. For a few labels, rendering every frame is fine too; the cache matters when a game shows many changing numbers.

Background, outline and shadow

The fourth argument of render paints a solid box behind the text:

label = font.render("PAUSED", True, "white", (0, 0, 0))

For a drop shadow, render the text twice in two colors and blit the dark copy a couple of pixels down and right first:

shadow = font.render("Game Over", True, (0, 0, 0))
text = font.render("Game Over", True, (255, 80, 80))
screen.blit(shadow, (102, 102))
screen.blit(text, (100, 100))

Several lines

pygame-ce's render() breaks lines at \n, and its fifth argument, wraplength, wraps long text at that many pixels:

import pygame

pygame.init()
screen = pygame.display.set_mode((480, 320))
clock = pygame.time.Clock()
font = pygame.font.Font(None, 30)

story = (
    "The ship's engine is broken. Collect five crystals "
    "to repair it before the oxygen runs out.\n\nGood luck, pilot."
)
text = font.render(story, True, (230, 230, 240), None, 400)

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

    screen.fill((20, 24, 44))
    pygame.draw.rect(screen, (70, 80, 120), (24, 24, 432, 272), width=2, border_radius=10)
    screen.blit(text, (40, 44))
    pygame.display.flip()
    clock.tick(60)

pygame.quit()

The original pygame does not break lines at \n and has no wraplength. There, split the text yourself and blit one line under the other:

for i, line in enumerate(lines):
    surface = font.render(line, True, "white")
    screen.blit(surface, (40, 44 + i * font.get_linesize()))

Measuring text

font.size("Hello") returns the width and height the text would take, without rendering it, which helps to lay out menus. font.get_linesize() is the recommended distance between lines.