Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/scanny/python-pptx/llms.txt

Use this file to discover all available pages before exploring further.

Autoshapes are predefined shapes like rectangles, circles, triangles, stars, and callouts. PowerPoint provides 182 different autoshape types, with 120 offering adjustment handles for customization.

​
Adding autoshapes

Add autoshapes using the add_shape() method with a shape type from MSO_SHAPE: 
from pptx import Presentation
from pptx.util import Inches
from pptx.enum.shapes import MSO_SHAPE

prs = Presentation()
slide = prs.slides.add_slide(prs.slide_layouts[5])

# Add a rounded rectangle
left = top = width = height = Inches(1.0)
shape = slide.shapes.add_shape(
    MSO_SHAPE.ROUNDED_RECTANGLE, left, top, width, height
)

prs.save('autoshape-example.pptx')

​
Available shape types

The MSO_SHAPE enumeration provides 182 shape types: 
from pptx.enum.shapes import MSO_SHAPE

# Basic shapes
MSO_SHAPE.RECTANGLE
MSO_SHAPE.ROUNDED_RECTANGLE
MSO_SHAPE.OVAL
MSO_SHAPE.TRIANGLE
MSO_SHAPE.DIAMOND
MSO_SHAPE.PENTAGON
MSO_SHAPE.HEXAGON

# Arrows
MSO_SHAPE.RIGHT_ARROW
MSO_SHAPE.LEFT_ARROW
MSO_SHAPE.UP_ARROW
MSO_SHAPE.DOWN_ARROW
MSO_SHAPE.LEFT_RIGHT_ARROW

# Callouts
MSO_SHAPE.RECTANGULAR_CALLOUT
MSO_SHAPE.ROUNDED_RECTANGULAR_CALLOUT
MSO_SHAPE.OVAL_CALLOUT
MSO_SHAPE.CLOUD_CALLOUT

# Stars and banners
MSO_SHAPE.STAR_5
MSO_SHAPE.STAR_8
MSO_SHAPE.RIBBON
MSO_SHAPE.WAVE

​
Understanding EMU (English Metric Units)

PowerPoint internally uses EMU for measurements. python-pptx provides conversion utilities: 
from pptx.util import Inches, Cm, Pt, Emu

# All these equal 1 inch:
Inches(1)      # → 914400 EMU
Cm(2.54)       # → 914400 EMU
Pt(72)         # → 914400 EMU
Emu(914400)    # → 914400 EMU

# Convert back to different units
length = Inches(1)
print(length.inches)  # → 1.0
print(length.cm)      # → 2.54
print(length.pt)      # → 72.0

​
Position and dimensions

Control shape position and size: 
from pptx.enum.shapes import MSO_SHAPE
from pptx.util import Inches

shape = slide.shapes.add_shape(
    MSO_SHAPE.ROUNDED_RECTANGLE,
    left=Inches(1),
    top=Inches(2),
    width=Inches(3),
    height=Inches(2)
)

# Read current dimensions
print(f"Left: {shape.left.inches} inches")
print(f"Top: {shape.top.inches} inches")
print(f"Width: {shape.width.inches} inches")
print(f"Height: {shape.height.inches} inches")

# Modify position and size
shape.left = Inches(2.0)
shape.top = Inches(3.0)
shape.width = Inches(4.0)
shape.height = Inches(3.0)

​
Fill formatting

Customize the interior appearance of shapes: 
from pptx.dml.color import RGBColor

fill = shape.fill
fill.solid()
fill.fore_color.rgb = RGBColor(0xFF, 0x00, 0x00)  # Red

​
Theme colors

Available theme color options from MSO_THEME_COLOR:
  • ACCENT_1 through ACCENT_6 - Theme accent colors
  • BACKGROUND_1, BACKGROUND_2 - Background colors
  • DARK_1, DARK_2 - Dark theme colors
  • LIGHT_1, LIGHT_2 - Light theme colors
  • HYPERLINK - Hyperlink color
  • FOLLOWED_HYPERLINK - Followed hyperlink color

​
Line formatting

Customize shape outlines: 
from pptx.util import Pt
from pptx.dml.color import RGBColor
from pptx.enum.dml import MSO_THEME_COLOR

line = shape.line

# Set color
line.color.rgb = RGBColor(0xFF, 0x00, 0x00)  # Red outline

# Or use theme color
line.color.theme_color = MSO_THEME_COLOR.ACCENT_6
line.color.brightness = 0.5  # 50% lighter

# Set width
line.width = Pt(2.5)

# Remove outline (transparent)
line.fill.background()

​
Shape adjustments

Many autoshapes have adjustment handles (yellow diamonds in PowerPoint) that modify their appearance: 
from pptx.enum.shapes import MSO_SHAPE

shape = slide.shapes.add_shape(
    MSO_SHAPE.ROUNDED_RECTANGLE,
    Inches(1), Inches(1),
    Inches(2), Inches(2)
)

# Access adjustments
adjs = shape.adjustments

# Check number of adjustments
print(len(adjs))  # Rounded rectangle has 1 adjustment

# Set adjustment value (0.0 to 1.0)
adjs[0] = 0.15  # More rounded corners

​
Understanding adjustment values

Adjustment values are normalized floats:
  • Nominal range: 0.0 to 1.0
  • Value of 0.5: Typically represents 50% of shape width/height
  • Negative values: Valid, may extend beyond shape boundaries
  • Values > 1.0: Valid, may extend beyond shape boundaries

​
Complex shape adjustments

Shapes can have multiple adjustments (up to 8): 
from pptx.enum.shapes import MSO_SHAPE

# Callout with multiple adjustments
callout = slide.shapes.add_shape(
    MSO_SHAPE.LINE_CALLOUT_2_ACCENT_BAR,
    Inches(1), Inches(1),
    Inches(3), Inches(2)
)

adjs = callout.adjustments

# Configure callout pointer
adjs[0] = 0.5   # Vertical position of junction
adjs[1] = 0.0   # Horizontal position of margin line
adjs[2] = 0.5   # Vertical position of elbow
adjs[3] = -0.1  # Horizontal position of elbow
adjs[4] = 3.0   # Vertical position of line end
adjs[5] = -0.2  # Horizontal position of line end

​
Rotation

Rotate shapes by setting the rotation property: 
shape = slide.shapes.add_shape(
    MSO_SHAPE.RIGHT_ARROW,
    Inches(1), Inches(1),
    Inches(3), Inches(1)
)

# Rotate 45 degrees counter-clockwise
shape.rotation = -45.0

# Rotate 90 degrees clockwise
shape.rotation = 90.0

​
Adding text to shapes

All autoshapes can contain text via their text frame: 
from pptx.util import Pt
from pptx.enum.text import PP_ALIGN

shape = slide.shapes.add_shape(
    MSO_SHAPE.ROUNDED_RECTANGLE,
    Inches(1), Inches(1),
    Inches(4), Inches(2)
)

# Add text
text_frame = shape.text_frame
text_frame.text = 'Hello World'

# Format text
p = text_frame.paragraphs[0]
p.alignment = PP_ALIGN.CENTER
p.font.size = Pt(24)
p.font.bold = True
See the Working with text guide for complete text formatting options.

​
Complete examples

from pptx import Presentation
from pptx.util import Inches, Pt
from pptx.enum.shapes import MSO_SHAPE
from pptx.enum.text import PP_ALIGN
from pptx.dml.color import RGBColor

prs = Presentation()
slide = prs.slides.add_slide(prs.slide_layouts[5])

def add_flowchart_shape(shape_type, text, left, top, color):
    shape = slide.shapes.add_shape(
        shape_type,
        Inches(left), Inches(top),
        Inches(2), Inches(1)
    )
    
    # Fill
    fill = shape.fill
    fill.solid()
    fill.fore_color.rgb = color
    
    # Text
    text_frame = shape.text_frame
    text_frame.text = text
    p = text_frame.paragraphs[0]
    p.alignment = PP_ALIGN.CENTER
    p.font.size = Pt(14)
    p.font.bold = True
    
    return shape

# Add flowchart shapes
add_flowchart_shape(
    MSO_SHAPE.ROUNDED_RECTANGLE, 'Start',
    3, 0.5, RGBColor(0x5B, 0x9B, 0xD5)
)
add_flowchart_shape(
    MSO_SHAPE.RECTANGLE, 'Process',
    3, 2, RGBColor(0x70, 0xAD, 0x47)
)
add_flowchart_shape(
    MSO_SHAPE.DIAMOND, 'Decision',
    3, 3.5, RGBColor(0xFF, 0xC0, 0x00)
)
add_flowchart_shape(
    MSO_SHAPE.ROUNDED_RECTANGLE, 'End',
    3, 5.5, RGBColor(0xC5, 0x50, 0x4E)
)

prs.save('flowchart.pptx')

​
Best practices

  • Use Inches(), Cm(), or Pt() for measurements instead of raw EMU values
  • Use theme colors when possible for consistency across presentations
  • Test adjustment values interactively in PowerPoint before coding
  • Group related shapes using the grouping functionality
  • Set explicit dimensions rather than relying on defaults
  • Use descriptive variable names when working with multiple adjustments
  • Consider shape rotation for dynamic layouts
To explore adjustment values, add a shape in PowerPoint, adjust it manually, then examine the XML using tools like opc-diag to see the generated values.

Build docs developers (and LLMs) love

Get started for freeTalk to us