Adding and Editing Layer Masks in GIMP: GUI Steps and a Python-Fu Script

The useful answer first

A layer mask in GIMP is a grayscale channel attached to a layer that hides or reveals parts of that layer without deleting anything. White areas of the mask are fully visible, black areas are fully transparent, and gray values produce partial transparency. To add one through the GUI: right-click the layer in the Layers dialog, choose Add Layer Mask, pick White (full opacity), then click the mask thumbnail and paint with black to conceal or white to reveal. To do it from a script, two PDB calls are enough:

mask = pdb.gimp_layer_create_mask(layer, ADD_MASK_WHITE)
pdb.gimp_layer_add_mask(layer, mask)

Everything below explains why this works, how to edit the mask safely, and where people typically go wrong.

How a mask actually works

When you erase pixels with the Eraser tool, the color data is gone. A mask instead sits alongside the layer as a separate grayscale bitmap. At render time GIMP multiplies the layer's alpha by the mask's value: a mask value of 255 (white) leaves the pixel untouched, 0 (black) forces it transparent, and anything in between produces partial transparency. Because the original pixels are never modified, you can repaint the mask white later and recover everything you hid.

This is why masks are the standard tool for compositing work such as blending two photos, cutting out a subject, or fading an edge: the edit stays reversible until you explicitly apply or discard the mask.

Adding and editing a mask in the GUI

1. Open your image and select the target layer in the Layers dialog (Windows → Dockable Dialogs → Layers if it is hidden).
2. Right-click the layer and choose Add Layer Mask. In GIMP 3.0 the same command also lives under Layer → Mask → Add Layer Mask; in some 3.0 themes the right-click entry moved to that submenu, so check both places.
3. In the dialog, choose White (full opacity). This is the safe default: the layer stays fully visible and you hide only what you paint.
4. Click the mask thumbnail (the white rectangle next to the layer preview). A white or green border indicates the mask, not the layer, is the active paint target.
5. Select the Paintbrush tool, set the foreground color to black, and paint over the areas you want to hide. Switch to white (press X to swap foreground/background) to reveal again. Use gray, a soft brush, or the Gradient tool for smooth transitions.

To check the result, toggle the eye icon on a background layer or look at the checkerboard pattern that indicates transparency. You can also Alt-click the mask thumbnail (in 2.10) to view the mask itself as a grayscale image, which is the fastest way to spot stray gray pixels.

Doing the same thing from Python-Fu

Open Filters → Development → Python-Fu → Console (GIMP 2.10; in GIMP 3.0 the console location may differ by build). The console runs as your user with the same permissions as GIMP itself, and it operates on the currently open image, so save your work first — a script can modify or destroy layer data.

# Assumes GIMP 2.10's Python-Fu console.
image = gimp.image_list()[0]          # first open image; pick the right one if several are open
layer = image.active_layer            # the layer currently selected in the Layers dialog

# Create a white (fully opaque) mask and attach it
mask = pdb.gimp_layer_create_mask(layer, ADD_MASK_WHITE)
pdb.gimp_layer_add_mask(layer, mask)

# Paint a black-to-transparent gradient effect by filling the mask
pdb.gimp_layer_set_edit_mask(layer, True)   # make the mask the paint target
pdb.gimp_context_set_foreground((0, 0, 0))  # black = hide
pdb.gimp_image_select_rectangle(image, CHANNEL_OP_REPLACE, 0, 0, 200, 200)
pdb.gimp_edit_fill(mask, FILL_FOREGROUND)
pdb.gimp_selection_none(image)
pdb.gimp_layer_set_edit_mask(layer, False)  # hand editing back to the layer
pdb.gimp_displays_flush()                   # refresh the canvas

Replace image_list()[0] with the correct index if you have multiple images open, and adjust the rectangle coordinates (x, y, width, height in pixels) to the region you want to hide. After running it, the expected result is a white mask thumbnail with a black 200×200 square, and the corresponding corner of the layer showing transparency. If nothing changed visually, the most likely cause is that the mask was never made the edit target — that is what gimp_layer_set_edit_mask(layer, True) does, mirroring the "click the mask thumbnail" step in the GUI.

Note the two-step pattern: gimp_layer_create_mask only creates the mask object; nothing appears until gimp_layer_add_mask attaches it. Forgetting the second call is the most common scripting mistake.

Limits and common mistakes

• Masks require raster layers. Text layers and some other special layer types cannot take a mask until you convert them (Layer → Rasterize, or right-click → Discard Text Information in 2.10). GIMP will refuse or grey out the command otherwise.
• Painting on the layer instead of the mask. If your black paint is visibly covering the image with black color rather than hiding it, the layer thumbnail is selected, not the mask. Click the mask thumbnail and repaint.
• Inverted colors. Black conceals, white reveals. If the effect is backwards, check the foreground color or press X. Also verify you did not initialize the mask as "Black (full transparency)", which hides the whole layer at once.
• Applying the mask makes it permanent. Right-click → Apply Layer Mask bakes the transparency into the layer and deletes the mask. Only do this when you are sure; otherwise keep the mask for later edits.
• Script-Fu vs Python-Fu. The PDB calls above are Python. In the Script-Fu console you need the Scheme form, e.g. (gimp-layer-create-mask layer ADD-MASK-WHITE); pasting Python into Script-Fu fails with an "unknown procedure" or syntax error.
• Version drift. These steps assume GIMP 2.10. GIMP 3.0 moved some menu entries (Layer → Mask submenu) and changed parts of the scripting API, so verify menu paths and PDB signatures against your installed version's Procedure Browser (Help → Procedure Browser).

Verifying it worked

Three quick checks: (1) the layer shows a mask thumbnail next to its preview; (2) painting black on the mask makes the checkerboard transparency pattern appear in the painted region; (3) switching the paint color to white restores the hidden pixels exactly, confirming nothing was erased. If all three hold, the mask is set up correctly and your edit remains fully reversible.