python-pptx

1.0.2 · active · verified Sun Mar 29

python-pptx is a Python library for creating, reading, and updating PowerPoint (.pptx) files. A typical use would be generating a PowerPoint presentation from dynamic content such as a database query, analytics output, or a JSON payload. It is currently at version 1.0.2 and aims for industrial-grade reliability with a comprehensive testing regimen.

Warnings

breaking Several API changes occurred around versions 0.6.x to 1.0.x, including enumeration renames (e.g., `pptx.enum.MSO_COLOR_TYPE` moved to `pptx.enum.dml.MSO_COLOR_TYPE`) and property renames (e.g., `SlideLayout.slidemaster` to `SlideLayout.slide_master`). Additionally, line-break encoding in `.text` properties changed from newline (\n) to vertical-tab (\v) in version 0.6.18 to better distinguish from paragraph boundaries.
Fix: Consult the release notes and official documentation for specific migration paths. Update code to use new enumeration paths and property names. Handle `\v` for line breaks when parsing or generating text.
gotcha The library exclusively supports PowerPoint Open XML files (`.pptx` format, introduced with PowerPoint 2007). Older PowerPoint `.ppt` files (PowerPoint 2003 and earlier) are not supported.
Fix: Ensure all input files are in the `.pptx` format. Convert older `.ppt` files using Microsoft PowerPoint if necessary.
gotcha When saving a presentation, if you specify a filename that already exists, `python-pptx` will overwrite the file silently without any warning or prompt.
Fix: Implement explicit checks or user confirmation mechanisms in your application before saving to an existing file path, or ensure unique filenames are generated.
gotcha Avoid directly instantiating internal classes (e.g., `pptx.presentation.Presentation`). Instead, use the `pptx.Presentation()` factory function to create a new presentation or load an existing one.
Fix: Always use `prs = Presentation()` or `prs = Presentation('path/to/file.pptx')`.
gotcha While `pip install python-pptx` typically handles core dependencies, if you use the `setup.py` installation method, or encounter issues with charting, verify that `XlsxWriter` is installed, as it is required for charting features.
Fix: If charting features are used and issues arise, explicitly install `XlsxWriter`: `pip install XlsxWriter`.

Install

pip install python-pptx Install stable version

Imports

Presentation
```
from pptx import Presentation
```
Inches
```
from pptx.util import Inches
```

Quickstart

This example demonstrates how to create a new PowerPoint presentation, add a title slide with text, and then add a blank slide with a custom textbox.

from pptx import Presentation
from pptx.util import Inches

# Create a new presentation
prs = Presentation()

# Add a title slide (layout index 0)
title_slide_layout = prs.slide_layouts[0]
slide = prs.slides.add_slide(title_slide_layout)

# Set title and subtitle
title = slide.shapes.title
subtitle = slide.placeholders[1]
title.text = "Hello, World!"
subtitle.text = "python-pptx was here!"

# Add a blank slide (layout index 6) and add a textbox
blank_slide_layout = prs.slide_layouts[6]
slide = prs.slides.add_slide(blank_slide_layout)
left = top = width = height = Inches(1.0)
textbox = slide.shapes.add_textbox(left, top, width, height)
textbox.text = "This is a custom textbox."

# Save the presentation
prs.save('test.pptx')
print("Presentation 'test.pptx' created successfully.")

view raw JSON →