python-pptx

library1.0.2pypypi✓ verified 27d ago

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.

serialization data

pip install python-pptx

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · PYTHON-PPTX

python-pptx

serializationpythonv1.0.2

Install

3.1s avg

Import

393ms

Disk

52MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.0.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.404s · 53.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.1s · import 0.382s · 55MB

52MB installed

● package 52MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Presentation

✓ from pptx import Presentation

Inches

✓ from pptx.util import Inches

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.")

Debug

Known issues

breakingSeveral 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.

affects: 0.6.1 and later, 0.6.18 and later

gotchaThe 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.

affects: All versions

gotchaWhen 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.

affects: All versions

gotchaAvoid 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')`.

affects: All versions

gotchaWhile `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`.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pptx'

The python-pptx library is installed via `pip install python-pptx` but its core package name for importing is `pptx`.

fix

Use `import pptx` or `from pptx import Presentation` to import the library.

AttributeError: 'Presentation' object has no attribute 'add_slide'

The `add_slide` method is called directly on the `Presentation` object instead of its `slides` collection.

fix

Access the `add_slide` method through the `slides` collection: `slide_layout = prs.slide_layouts[0]
slide = prs.slides.add_slide(slide_layout)`

KeyError: 'chart_type'

An invalid or misspelled chart type is provided when attempting to add a chart to a slide.

fix

Use a valid `builtin_chart_type` enum member from `pptx.enum.chart`, for example: `XL_CHART_TYPE.COLUMN_CLUSTERED`.

FileNotFoundError: [Errno 2] No such file or directory: 'template.pptx'

The specified path to the presentation file (for loading or saving) is incorrect, or the file does not exist at that location.

fix

Ensure the file exists and the path (absolute or relative) is correct, for example: `prs = Presentation('path/to/your/template.pptx')`.

Upgrade

Version history

1.0.2latest on PyPI · released Aug 7, 2024

Audit

Dependencies

lxmlrequiredRequired for parsing and generating Open XML files.

PillowrequiredRequired for image manipulation.

XlsxWriteroptionalRequired for advanced charting features.

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/scanny/python-pptx ↗

packagehttps://pypi.org/project/python-pptx/ ↗

docshttps://python-pptx.readthedocs.io/en/latest/ ↗

changeloghttps://github.com/scanny/python-pptx/blob/master/HISTORY.rst ↗