Concepts

python-pptx is completely object-oriented, and in general any operations you perform with it will be on an object. The root object for a presentation is Presentation. API details are provided on the modules pages, but here are some basics to get you started, especially some relationships you might find surprising at first.

A presentation is loaded by constructing a new Presentation instance, passing in the path to a presentation to be loaded:

from pptx import Presentation

path = 'slide-deck-foo.pptx'
prs = Presentation(path)

python-pptx also contains a default template, and if you construct a Presentation instance without a path, a presentation based on that default template is loaded. This can be handy when you want to get started quickly, and most of the examples in this documentation use the default template.:

# start with default presentation
prs = Presentation()

Note that there is currently no distinction between templates and presentations in python-pptx as there is in the PowerPoint® client, there are only presentations. To use a “template” for a presentation you simply create a presentation with all the styles, logo, and layouts you want, delete all the slides (or leave some in if it suits), and then load that as your starting place.

Slide masters

A presentation has a list of slide masters and a list of slides. Let’s start with a discussion of the slide masters.

One fact some find surprising (I did) is that a presentation file can have more than one slide master. It’s quite uncommon in my experience to find presentations that make use of this feature, but it’s entirely supported. The only time I’ve seen this happen is when slides from a “foreign” presentation are pasted into another deck; if you want the formatting and backgrounds from the other deck to be preserved on the pasted-in slides, the slide master and its slide layouts need to come with. Consequently, the presentation needs to maintain a list of slide masters, not just a single one, even though perhaps 99% of the time you only ever use the one. To make things a little easier for the 99% situation, you can refer to the first slide master as though it were the only one:

prs = Presentation()
slide_master = prs.slide_masters[0]
# is equivalent to
slide_master = prs.slide_master

Slide layouts

Another fact that might be surprising is that slide layouts belong to a slide master, not directly to a presentation, so normally you have to access the slide layouts via their slide master. Since this is subject to the same 99% situation described above, the slide layouts belonging to the first slide master can also be accessed directly from the presentation via syntactic sugar:

prs = Presentation()
title_slide_layout = prs.slide_masters[0].slide_layouts[0]
# is equivalent to:
title_slide_layout = prs.slide_layouts[0]

Slides

The slides in a presentation belong to the presentation object and are accessed using the slides attribute:

prs = Presentation(path)
first_slide = prs.slides[0]

Adding a slide

Adding a slide is accomplished by calling the add_slide() method on the slides attribute of the presentation. A slide layout must be passed in to specify the layout the new slide should take on:

prs = Presentation()
title_slide_layout = prs.slide_layouts[0]
new_slide = prs.slides.add_slide(title_slide_layout)