Skip to main content

​
Quickstart

Get up and running with python-pptx by creating your first presentation. This guide will walk you through the basics of creating slides, adding content, and saving your presentation.

​
Your first presentation

Let’s create a simple “Hello, World!” presentation to get familiar with the basics.

​
Hello, World! example

1

Import the Presentation class

Start by importing the main Presentation class from the pptx module:
from pptx import Presentation
2

Create a new presentation

Create a new, empty presentation object:
prs = Presentation()
This creates a presentation based on the default template, which includes several slide layouts.
3

Choose a slide layout

Select a slide layout to use. The default template includes 11 layouts. Layout [0] is the title slide:
title_slide_layout = prs.slide_layouts[0]
4

Add a slide

Add a new slide using the selected layout:
slide = prs.slides.add_slide(title_slide_layout)
5

Add content to the slide

Access the title and subtitle placeholders and set their text:
title = slide.shapes.title
subtitle = slide.placeholders[1]

title.text = "Hello, World!"
subtitle.text = "python-pptx was here!"
6

Save the presentation

Save your presentation to a file:
prs.save('hello_world.pptx')

​
Complete code

Here’s the complete “Hello, World!” example: 
from pptx import Presentation

prs = Presentation()
title_slide_layout = prs.slide_layouts[0]
slide = prs.slides.add_slide(title_slide_layout)
title = slide.shapes.title
subtitle = slide.placeholders[1]

title.text = "Hello, World!"
subtitle.text = "python-pptx was here!"

prs.save('hello_world.pptx')
Run this code and open the resulting hello_world.pptx file in PowerPoint to see your first programmatically created presentation!

​
Understanding the basics

​
The Presentation object

The Presentation class is the top-level object representing your PowerPoint file. 
from pptx import Presentation

# Create a new presentation (uses default template)
prs = Presentation()

# Open an existing presentation
prs = Presentation('existing.pptx')

​
Slide layouts

Slide layouts define the arrangement of placeholders on a slide. The default template provides 11 layouts:
  • slide_layouts[0] - Title Slide
  • slide_layouts[1] - Title and Content
  • slide_layouts[2] - Section Header
  • slide_layouts[3] - Two Content
  • slide_layouts[4] - Comparison
  • slide_layouts[5] - Title Only
  • slide_layouts[6] - Blank
  • slide_layouts[7] - Content with Caption
  • slide_layouts[8] - Picture with Caption
  • And more…
# Access available layouts
for i, layout in enumerate(prs.slide_layouts):
    print(f"Layout {i}: {layout.name}")

​
Adding slides

Always add slides using a layout: 
# Add a title slide
title_slide = prs.slides.add_slide(prs.slide_layouts[0])

# Add a content slide
content_slide = prs.slides.add_slide(prs.slide_layouts[1])

# Add a blank slide
blank_slide = prs.slides.add_slide(prs.slide_layouts[6])

​
Adding content to slides

​
Working with text

​
Using placeholders

Placeholders are predefined text areas in a slide layout: 
slide = prs.slides.add_slide(prs.slide_layouts[1])

# Access the title placeholder
title_shape = slide.shapes.title
title_shape.text = "Slide Title"

# Access other placeholders by index
body_shape = slide.placeholders[1]
body_shape.text = "This is body text"

​
Adding bullet points

from pptx import Presentation

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

title_shape = slide.shapes.title
body_shape = slide.placeholders[1]

title_shape.text = "Adding Bullet Points"

# Get the text frame
tf = body_shape.text_frame
tf.text = "First bullet point"

# Add more paragraphs for additional bullets
p = tf.add_paragraph()
p.text = "Second bullet point"
p.level = 0  # Top-level bullet

p = tf.add_paragraph()
p.text = "Indented bullet point"
p.level = 1  # Second-level bullet

prs.save('bullets.pptx')

​
Adding text boxes

Create text boxes with custom positioning and size: 
from pptx import Presentation
from pptx.util import Inches, Pt

prs = Presentation()
blank_slide = prs.slides.add_slide(prs.slide_layouts[6])

# Define position and size
left = top = Inches(1)
width = height = Inches(3)

# Add text box
txBox = blank_slide.shapes.add_textbox(left, top, width, height)
tf = txBox.text_frame
tf.text = "This is text inside a textbox"

# Add formatted paragraph
p = tf.add_paragraph()
p.text = "This is bold text"
p.font.bold = True

p = tf.add_paragraph()
p.text = "This is large text"
p.font.size = Pt(40)

prs.save('textbox.pptx')

​
Adding images

Insert images into your slides: 
from pptx import Presentation
from pptx.util import Inches

prs = Presentation()
blank_slide = prs.slides.add_slide(prs.slide_layouts[6])

# Add image at specific position
img_path = 'path/to/image.png'
left = Inches(1)
top = Inches(1)
pic = blank_slide.shapes.add_picture(img_path, left, top)

# Add image with specific height (width auto-calculated)
left = Inches(5)
height = Inches(4)
pic = blank_slide.shapes.add_picture(img_path, left, top, height=height)

prs.save('with_images.pptx')

​
Adding shapes

Create various shapes programmatically: 
from pptx import Presentation
from pptx.enum.shapes import MSO_SHAPE
from pptx.util import Inches

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

shapes.title.text = "Adding Shapes"

# Add a rectangle
left = Inches(1)
top = Inches(2)
width = Inches(2)
height = Inches(1)

shape = shapes.add_shape(
    MSO_SHAPE.RECTANGLE,
    left, top, width, height
)
shape.text = "Rectangle"

# Add other shapes
shape = shapes.add_shape(
    MSO_SHAPE.ROUNDED_RECTANGLE,
    Inches(4), Inches(2), Inches(2), Inches(1)
)
shape.text = "Rounded"

prs.save('shapes.pptx')

​
Adding tables

Create tables with rows and columns: 
from pptx import Presentation
from pptx.util import Inches

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

shapes.title.text = "Adding a Table"

# Define table dimensions and position
rows = cols = 3
left = top = Inches(2)
width = Inches(6)
height = Inches(2)

# Add table
table = shapes.add_table(rows, cols, left, top, width, height).table

# Set column widths
table.columns[0].width = Inches(2)
table.columns[1].width = Inches(2)
table.columns[2].width = Inches(2)

# Populate cells
table.cell(0, 0).text = "Header 1"
table.cell(0, 1).text = "Header 2"
table.cell(0, 2).text = "Header 3"

table.cell(1, 0).text = "Row 1, Col 1"
table.cell(1, 1).text = "Row 1, Col 2"
table.cell(1, 2).text = "Row 1, Col 3"

prs.save('table.pptx')

​
Working with measurements

python-pptx uses English Metric Units (EMU) internally, but provides convenient classes for common units: 
from pptx.util import Inches, Cm, Mm, Pt

# Different ways to specify measurements
width = Inches(2)      # 2 inches
height = Cm(5)         # 5 centimeters
left = Mm(25)          # 25 millimeters
font_size = Pt(18)     # 18 points

# Convert between units
width_in_cm = width.cm
width_in_mm = width.mm
width_in_pt = width.pt
All measurement classes (Inches, Cm, Mm, Pt) are interchangeable. Use whichever unit is most convenient for your use case.

​
Reading existing presentations

You can also open and modify existing presentations: 
from pptx import Presentation

# Open an existing presentation
prs = Presentation('existing.pptx')

# Access slides
for slide in prs.slides:
    print(f"Slide has {len(slide.shapes)} shapes")

# Extract text from all slides
for slide in prs.slides:
    for shape in slide.shapes:
        if shape.has_text_frame:
            for paragraph in shape.text_frame.paragraphs:
                for run in paragraph.runs:
                    print(run.text)

# Add a new slide to existing presentation
new_slide = prs.slides.add_slide(prs.slide_layouts[1])
new_slide.shapes.title.text = "New Slide Added"

# Save the modified presentation
prs.save('modified.pptx')

​
Next steps

Now that you’ve created your first presentation, explore more advanced features:

API Reference

Explore the complete API documentation

Working with charts

Learn how to add charts and graphs to your presentations

Text formatting

Master fonts, colors, and text styling

Core Concepts

Learn about presentations, slides, and shapes

​
Common patterns

​
Generate reports from data

from pptx import Presentation
from pptx.util import Inches

# Sample data
data = [
    {"quarter": "Q1", "revenue": 1250000},
    {"quarter": "Q2", "revenue": 1350000},
    {"quarter": "Q3", "revenue": 1450000},
    {"quarter": "Q4", "revenue": 1550000},
]

prs = Presentation()

for item in data:
    slide = prs.slides.add_slide(prs.slide_layouts[1])
    slide.shapes.title.text = f"{item['quarter']} Report"
    
    body = slide.placeholders[1]
    tf = body.text_frame
    tf.text = f"Revenue: ${item['revenue']:,.2f}"

prs.save('quarterly_report.pptx')

​
Create a photo album

from pptx import Presentation
from pptx.util import Inches
import os

prs = Presentation()

# Add title slide
title_slide = prs.slides.add_slide(prs.slide_layouts[0])
title_slide.shapes.title.text = "My Photo Album"

# Add photos from a directory
image_dir = 'photos'
for img_file in os.listdir(image_dir):
    if img_file.endswith(('.jpg', '.png')):
        slide = prs.slides.add_slide(prs.slide_layouts[6])  # Blank layout
        img_path = os.path.join(image_dir, img_file)
        
        # Center the image
        slide.shapes.add_picture(
            img_path,
            Inches(0.5),
            Inches(0.5),
            height=Inches(6.5)
        )

prs.save('photo_album.pptx')
Check out the Working with Content guides for more real-world use cases and code samples.

Build docs developers (and LLMs) love

Get started for freeTalk to us