Why does PixelArray lock the surface?

PixelArray exposes raw pixel memory directly — the surface can’t be drawn from while another reader holds the lock. The lock prevents concurrent draw operations from corrupting pixel data mid-edit. Delete the PixelArray (del pa or pa.close()) to release.

How do I write pixels without manual lock management?

Use pygame.surfarray.pixels3d(surf) or surfarray.array3d for numpy integration; or set_at((x,y), color) for one-off writes. surfarray returns a numpy view that’s much faster than PixelArray for bulk edits, and surfarray.blit_array commits at end.

What's the fastest way to draw many pixels in Pygame?

surfarray with numpy. Build a numpy array of the desired colors and call surfarray.blit_array(surf, arr). Single CPU pass through pixel memory; orders of magnitude faster than per-pixel set_at calls.

Fix: Pygame PixelArray Write Not Reflecting on Surface

Quick answer: PixelArray locks the surface. Delete the array (del pa or pa.close()) before calling blit on the surface. Or use surfarray with numpy, which is faster and handles locks cleanly.

You build a procedural texture by writing pixels to a Surface via PixelArray, then blit the surface. The screen shows the texture’s previous state — or nothing. Your writes happened but aren’t visible. The PixelArray is still alive when you tried to blit.

The Lock

PixelArray obtains a write lock on the surface. While locked:

Reading pixels via PixelArray succeeds.
Writing pixels via PixelArray succeeds (the writes go to the underlying buffer).
Drawing the surface via blit may fail or use stale data because the source is locked for another operation.

The fix is to release the lock before drawing.

The Fix

import pygame

surf = pygame.Surface((128, 128))

pa = pygame.PixelArray(surf)
for y in range(128):
    for x in range(128):
        pa[x, y] = (x * 2, y * 2, 0)
del pa   # release the lock

screen.blit(surf, (0, 0))

The del pa destroys the PixelArray instance, releasing the lock. Now the blit reads from a non-locked surface and the writes are visible.

Use a Context Manager

with pygame.PixelArray(surf) as pa:
    for y in range(128):
        for x in range(128):
            pa[x, y] = (x * 2, y * 2, 0)
screen.blit(surf, (0, 0))

The with block releases the lock automatically on exit. Clean and harder to leak.

Faster: surfarray with numpy

PixelArray is slow for bulk edits because every assignment goes through Python. numpy-backed surfarray is much faster:

import numpy as np
import pygame
import pygame.surfarray

surf = pygame.Surface((128, 128))
arr = np.zeros((128, 128, 3), dtype=np.uint8)

# vectorized fill
x_idx = np.arange(128)[:, None]
y_idx = np.arange(128)[None, :]
arr[:, :, 0] = (x_idx * 2).astype(np.uint8)
arr[:, :, 1] = (y_idx * 2).astype(np.uint8)

pygame.surfarray.blit_array(surf, arr)
screen.blit(surf, (0, 0))

Roughly 100× faster for a 128×128 surface and locks handled internally by surfarray.

Per-Pixel Convenience: set_at

For a few pixels — under 1000 — surface.set_at((x, y), color) is the simplest path. It manages its own short-lived lock per call. Don’t use for bulk fills; the per-call overhead is too high.

Verifying

Print surf.get_locks() after your edit code. An empty list means the surface is unlocked and ready to blit. A non-empty list shows a lingering PixelArray reference.

“PixelArray writes go through. The lock just prevents you seeing them until released.”

For procedurally generated textures, numpy + surfarray is the only realistic choice — PixelArray is too slow for animation frame rates.