WolfSDKWolfXLWolfPPTWolfDocxWolfRender

WolfPPT - placeholder lookup errors

How do I fix python-pptx placeholder KeyError when editing slide master layouts?

A python-pptx placeholder KeyError usually means the requested placeholder idx is not present in that collection, not that the second shape has disappeared. Inspect the actual placeholders and select their placeholder_format.idx values rather than their positions. Fix that lookup in python-pptx first; switching libraries does not create a missing placeholder.

Why a numbered placeholder can be missing

The python-pptx placeholder guide says item access is dictionary-like: slide.placeholders[1] requests the placeholder whose idx is one, not the second item. Values need not be contiguous. A slide with two placeholders therefore need not accept keys zero and one, and a shape's shape_id is not a substitute for its placeholder index.

A slide, its layout, and its master are different owners. The same documentation explains that slide placeholders inherit formatting from layout placeholders, while layout placeholders inherit from the master. Do not take an index from a master inventory and assume it identifies a placeholder on the slide. Inspect each owner separately and decide whether you intend to change slide content or template design.

Fix the python-pptx lookup first

Install python-pptx and use an existing pitch-template.pptx with at least one slide. This example targets a text placeholder with index zero on the first slide. Change wanted_idx to the key printed for your intended placeholder. A missing required target produces an explicit template error instead of silently editing a different shape.

from pptx import Presentation

prs = Presentation("pitch-template.pptx")
slide = prs.slides[0]
for label, owner in (("slide", slide), ("layout", slide.slide_layout),
                     ("master", slide.slide_layout.slide_master)):
    print(label, [(p.placeholder_format.idx, p.name) for p in owner.placeholders])

wanted_idx = 0  # choose an idx printed for the slide, not a list position
matches = [p for p in slide.placeholders if p.placeholder_format.idx == wanted_idx]
if not matches:
    raise ValueError(f"Template has no slide placeholder with idx={wanted_idx}")
placeholder = slide.placeholders[wanted_idx]
if not placeholder.has_text_frame:
    raise ValueError("Choose a text placeholder from the inventory")
placeholder.text = "Acme Robotics: Series A"
prs.save("pitch-title-fixed.pptx")

To edit a layout or master, inspect that owner's printed objects and choose the property there. The code deliberately writes slide text only. It does not add a placeholder to a master, rebuild a layout, or assume that changing a layout erases overrides already stored on individual slides.

Other errors that need a different diagnosis

If the exception comes from a different call, keep the traceback rather than treating every “shape not found” message as this index problem. The upstream guide also warns that rich-content insertion replaces the placeholder element: after insert_picture, insert_table, or insert_chart, use the returned object or reacquire the placeholder. A stale reference and a nonexistent index are separate problems and need different fixes.

What WolfPPT offers for an existing slide

WolfPPT 0.1.6 can enumerate slide placeholders, read their indexes, and edit existing text runs. With wolfppt installed, this second example uses a title placeholder at index zero containing at least one paragraph and run. Run-level assignment keeps that run's formatting rather than replacing its entire text frame.

from wolfppt import Presentation

prs = Presentation("pitch-template.pptx")
slide = prs.slides[0]
for placeholder in slide.placeholders:
    print(placeholder.placeholder_format.idx, placeholder.name)
slide.placeholders[0].text_frame.paragraphs[0].runs[0].text = "Acme Robotics"
prs.save("pitch-title-wolfppt.pptx")

What it does not do

  • WolfPPT uses idx lookup too. It raises KeyError for an absent slide placeholder rather than guessing.
  • The examples do not create missing placeholders or repair a malformed template.
  • The python-pptx assignment replaces the whole placeholder text; it does not preserve its mixed run styling.
  • Do not infer full master/layout mutation support in the pip release from newer source examples. A layout placeholder's left geometry property is not exposed in 0.1.6.
  • No PDF rendering or PowerPoint visual-equivalence claim is part of this text-editing workflow.

Continue with text edits, the migration call map, or the python-pptx comparison.

Install WolfPPT

The public WolfPPT Community release is MIT-licensed and free, including commercial use. WolfPPT Commercial does not change those rights.

pip install wolfppt

PyPI wheels cover CPython 3.11 to 3.14 on Linux x86_64 and aarch64 and on macOS arm64. Source, tests, and the full facade reference live at github.com/wolfiesch/wolfppt-oss.

Related tasks