Why is my Pygame text blurry on Retina/HiDPI screens?

Pygame surface is the logical resolution; the OS upscales to physical pixels. Use pygame.display.set_mode with SCALED flag so SDL renders at native pixel density.

Should I render the whole game at 2x?

For sharp text and UI: yes. Multiply font sizes by Display.get_window_size scale; pygame.SCALED handles physical-vs-logical translation.

freetype offers crisp hinting and rotation. For fixed pixel-grid UI, set Font.set_strong(False), or use freetype Font with Antialiased=True and Hinting='normal'.

Fix: Pygame Text Blurry On HiDPI Display

Quick answer: pygame.display.set_mode((w, h), pygame.SCALED). Render at 2x logical size. Use freetype with normal hinting.

macOS Retina screen. Pygame text fuzzy. Default surface is logical pixels; OS scales to physical, blurring along the way.

The Fix

import pygame
pygame.init()

screen = pygame.display.set_mode(
    (1280, 720),
    pygame.SCALED | pygame.RESIZABLE
)

# Font: pygame.freetype with hint
import pygame.freetype
font = pygame.freetype.Font("Inter.ttf", 24)
font.antialiased = True
font.render_to(screen, (10, 10), "Hello", (255,255,255))

SCALED tells SDL to upscale at the native pixel level rather than relying on OS magnification. Combined with antialiased freetype, text renders crisply.

Verifying

HiDPI display: text edges remain crisp under zoom. Without SCALED: pixelation visible at native resolution.

“SCALED flag. freetype antialias. Crisp text on Retina.”

Related Issues

For Rect float warning, see Rect warning. For Clock vsync, see Clock vsync.

SCALED. Antialias. Crisp.