Python pptx, как установить библиотеку и создать презентацию кодом?

Python-pptx это библиотека для Python, которая создаёт, читает и изменяет файлы PowerPoint в формате PPTX прямо из кода. Устанавливается она одной командой pip install python-pptx, а сам PowerPoint для её работы не нужен: скрипт запускается на любой системе, где есть Python. Типичная задача выглядит так: взять данные из таблицы или базы и автоматически собрать из них готовую презентацию. Порядок работы:

1. Установите Python 3.8 или новее.
2. Создайте виртуальное окружение и активируйте его.
3. Выполните pip install python-pptx.
4. Напишите скрипт: создайте Presentation, добавьте слайды, текст, таблицы или графики.
5. Сохраните результат методом save и откройте файл в PowerPoint.

Мы проверили примеры из статьи на версии 1.0.2, последней на PyPI: все они отработали и дали корректный PPTX. Ниже разберём установку, основные объекты библиотеки и ограничения, о которых лучше знать заранее.

Нужна презентация без единой строки кода? Попробуйте AI для презентаций в сервисе SimpleSlide: слайды генерируются с помощью ИИ примерно за 1 минуту. Достаточно ввести тему или вставить свой текст, и вы получите готовый шаблон, который легко отредактировать или сразу скачать в PPTX или PDF.

Что такое python-pptx и для чего он нужен?

Какие задачи решает библиотека?

Документация называет типичный сценарий: сгенерировать презентацию из динамических данных, например результата запроса к базе, аналитики или JSON, иногда прямо в ответ на HTTP-запрос. Второй сценарий обратный: разобрать готовые файлы и вытащить из них текст и картинки, например для поискового индекса. Третий самый житейский: автоматизировать пару слайдов, которые утомительно каждый раз собирать руками. По словам автора, именно с этого всё и началось.

Нужен ли установленный PowerPoint?

Нет, и это главное отличие от автоматизации через сам Office. Документация говорит об этом прямо:

Она работает на любой платформе, где есть Python, включая macOS и Linux, и не требует установки или лицензии приложения PowerPoint (перевод наш).

Оригинал: «It runs on any Python capable platform, including macOS and Linux, and does not require the PowerPoint application to be installed or licensed».

Поэтому библиотеку часто ставят на сервер: там нет Office, но есть Python, и отчёты собираются по расписанию. Распространяется она под свободной лицензией MIT, так что подходит и для коммерческих проектов.

Чем это отличается от других способов автоматизации?

Есть три привычных пути. Макросы VBA живут внутри PowerPoint и без установленного Office не работают. API Google Презентаций управляет файлами в облаке Google и требует настройки доступа к аккаунту. Python-pptx работает с самим файлом на диске: ни программы, ни облака, ни входа в аккаунт. Для отчётов на сервере это самый простой вариант. Для живой совместной работы над слайдами удобнее облачные редакторы.

Python pptx как установить?

Какая версия Python подойдёт?

По данным PyPI, текущая версия python-pptx 1.0.2 вышла 7 августа 2024 года и требует Python 3.8 или новее. На странице установки в документации до сих пор упоминаются Python 2.7 и 3.3, но это устаревший текст: ориентируйтесь на требования PyPI. Вместе с библиотекой pip сам поставит зависимости: lxml, Pillow для работы с картинками и XlsxWriter, который нужен для графиков.

Зачем виртуальное окружение?

Чтобы пакеты проекта не смешивались с системными. Документация Python объясняет понятие так:

Виртуальное окружение это частично изолированная среда Python, в которую пакеты ставятся для конкретного приложения, а не для всей системы (перевод наш).

Оригинал: «A virtual environment is a semi-isolated Python environment that allows packages to be installed for use by a particular application, rather than being installed system wide».

Какие команды выполнить?

На Windows в командной строке или PowerShell:

py -m venv .venv
.venvScriptsactivate
python -m pip install python-pptx

На macOS и Linux:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install python-pptx

Проверить, что всё встало, можно одной строкой: python -c "import pptx; print(pptx.__version__)". Если библиотека уже стоит, повторная установка ничего не изменит, для перехода на свежую версию нужен флаг --upgrade. Ещё одна мелочь, на которой спотыкаются новички: пакет ставится как python-pptx, а в коде импортируется как pptx.

Как создать первую презентацию на Python?

Из чего состоит минимальный скрипт?

Основа всего объект Presentation. Без аргументов он создаёт пустую презентацию на встроенном шаблоне, с аргументом открывает существующий файл. Слайды добавляются через макеты: prs.slide_layouts[0] это титульный слайд, [1] заголовок и содержимое. Вот рабочий пример:

from pptx import Presentation

prs = Presentation()
layout = prs.slide_layouts[0]
slide = prs.slides.add_slide(layout)
slide.shapes.title.text = "Отчёт за квартал"
slide.placeholders[1].text = "Собрано скриптом"
prs.save("report.pptx")

После запуска рядом со скриптом появится report.pptx с одним титульным слайдом. Кириллица работает без дополнительных настроек, мы проверили это на русских заголовках.

Какие макеты есть во встроенном шаблоне?

Мы вывели их список из кода, в шаблоне по умолчанию 11 макетов. Индекс нужен, чтобы выбрать макет при добавлении слайда:

Как добавить текст, таблицу и график?

Как работать с текстом?

У каждой фигуры с текстом есть text_frame. Первый абзац задаётся через text, следующие через add_paragraph, а уровень вложенности списка через level. Размер шрифта меняется у фрагмента текста: run.font.size = Pt(40). Для свободной надписи на пустом слайде есть slide.shapes.add_textbox с координатами и размерами в дюймах.

slide = prs.slides.add_slide(prs.slide_layouts[1])
slide.shapes.title.text = "Итоги"
tf = slide.placeholders[1].text_frame
tf.text = "Выручка выросла"
p = tf.add_paragraph()
p.text = "Новых клиентов 120"
p.level = 1

Как вставить таблицу?

Метод add_table принимает число строк и столбцов, позицию и размер. Ячейки заполняются через table.cell(строка, столбец).text. Оформление по умолчанию берётся из темы шаблона, поэтому таблица сразу выглядит аккуратно. Как оформлять таблицы на слайде вручную, мы рассказывали в статье о таблицах в PowerPoint.

Как построить график?

Данные собираются в объект CategoryChartData: категории и одна или несколько серий. Затем add_chart с типом из XL_CHART_TYPE. Библиотека поддерживает столбчатые, линейчатые, линейные и круговые диаграммы, и в PowerPoint они остаются настоящими редактируемыми графиками, а не картинками.

from pptx.chart.data import CategoryChartData
from pptx.enum.chart import XL_CHART_TYPE
from pptx.util import Inches

data = CategoryChartData()
data.categories = ["Янв", "Фев", "Мар"]
data.add_series("Продажи", (12, 15, 19))
slide.shapes.add_chart(
    XL_CHART_TYPE.COLUMN_CLUSTERED,
    Inches(1), Inches(1.5), Inches(8), Inches(5),
    data)

Какой тип диаграммы выбрать под конкретные данные, подскажет наш разбор видов диаграмм для презентации.

Как вставить картинку?

Для изображений есть метод add_picture: путь к файлу, отступ слева, отступ сверху и, по желанию, ширина или высота. Если задать только ширину, высота посчитается сама с сохранением пропорций. Мы проверили на картинке 400 на 300 пикселей: при ширине 4 дюйма она получила высоту ровно 3 дюйма. Так удобно ставить логотип в угол каждого слайда или фото товара на карточку, не думая о том, что изображение растянется.

Что ещё умеет библиотека?

Список возможностей из документации

• Открывать и сохранять любой файл .pptx со всеми его элементами.
• Добавлять слайды и заполнять текстовые заполнители, например для слайда со списком.
• Вставлять изображения в любое место и любого размера.
• Добавлять надписи, менять размер шрифта и жирность.
• Добавлять таблицы и автофигуры, включая многоугольники и фигуры блок-схем.
• Строить столбчатые, линейчатые, линейные и круговые диаграммы.
• Читать и менять свойства документа, например заголовок и тему.

В API также есть заметки докладчика: slide.notes_slide.notes_text_frame. Мы проверили, текст заметки сохраняется в файл и читается обратно.

Как заполнить свойства документа?

У презентации есть набор служебных полей: заголовок, тема, автор и другие. В python-pptx они доступны через prs.core_properties. В пустой презентации заголовок пустой, мы это проверили. Заполните его перед сохранением. Мелочь? Да. Но так файл проще найти в поиске по папке, а у получателя в свойствах будет не пустая строка, а понятное название отчёта.

Как прочитать готовую презентацию?

Откройте файл через Presentation("имя.pptx") и пройдите по слайдам и фигурам. У каждой фигуры можно спросить has_text_frame, has_table или has_chart и забрать содержимое. Так удобно собирать текст из десятков презентаций в один документ или проверять, что на всех слайдах стоит нужный логотип и шрифт.

Как собрать отчёт из таблицы с данными?

Какой порядок действий?

Покажем на простом примере: есть CSV-файл с городами и продажами, и для каждого города нужен отдельный слайд. В реальной жизни вместо CSV может быть выгрузка из Excel, ответ API или запрос к базе, но логика та же.

1. Прочитайте данные стандартным модулем csv или библиотекой pandas.
2. Откройте шаблон презентации или создайте пустую.
3. Для каждой строки данных добавьте слайд нужного макета.
4. Заполните заголовок и текст значениями из строки.
5. Сохраните файл под именем с датой, чтобы выпуски не затирали друг друга.

import csv
from pptx import Presentation

prs = Presentation()
with open("sales.csv", encoding="utf-8") as f:
    for row in csv.DictReader(f):
        s = prs.slides.add_slide(prs.slide_layouts[1])
        s.shapes.title.text = row["city"]
        s.placeholders[1].text = "Продажи: " + row["sales"]
prs.save("sales_report.pptx")

Что получится на выходе?

На тестовом файле из двух строк скрипт создал презентацию ровно из двух слайдов, по одному на город. Если в CSV тысяча строк, слайдов будет тысяча, поэтому для больших выгрузок данные лучше сначала сгруппировать. Обычно хватает одного итогового графика и пары таблиц, а подробности уходят в приложение. Не забудьте указать кодировку utf-8 при чтении: без неё русские названия на Windows могут превратиться в набор непонятных символов ещё до того, как попадут на слайд.

Какие у python-pptx ограничения?

Чего библиотека не делает?

Документация честно предупреждает: формат PowerPoint очень богатый, и часть функций библиотека не поддерживает. Новые возможности обычно появляются через спонсорство, так добавили, например, графики. Вот что чаще всего удивляет на практике:

Как обойти ограничения с дизайном?

Самый удобный путь: сделать шаблон с фирменными цветами, шрифтами и макетами в PowerPoint, сохранить его как PPTX и открывать в скрипте через Presentation("template.pptx"). Тогда код только наполняет готовые заполнители, а за внешний вид отвечает дизайнер. Перед этим удалите из шаблона лишние слайды, иначе они окажутся в каждом отчёте. Как правильно сохранить такой файл, описано в материале о сохранении презентации в PPTX.

Какие ошибки встречаются чаще всего?

Что означают типичные сообщения?

• ModuleNotFoundError с именем pptx: библиотека стоит в другом окружении. Активируйте нужное или поставьте пакет через python -m pip, чтобы он попал именно в тот интерпретатор, которым вы запускаете скрипт.
• PackageNotFoundError при открытии файла: путь неверный или файл вовсе не PPTX. Мы получили эту ошибку и для несуществующего файла, и для текстового файла с расширением .pptx.
• KeyError при обращении к placeholders: у выбранного макета нет заполнителя с таким номером. На пустом макете Blank их нет совсем, туда текст добавляют через add_textbox.
• Ошибка доступа при сохранении на Windows: часто это значит, что файл с тем же именем открыт в PowerPoint. Закройте его или сохраните под другим именем.

Как отлаживать скрипт быстрее?

Выведите список макетов шаблона и номера их заполнителей перед тем, как писать основной код. Это пара строк: перебрать prs.slide_layouts, а у каждого макета placeholders с полем placeholder_format.idx. Так вы сразу увидите, куда можно вставлять текст, и не будете гадать по номерам. Сохраняйте промежуточный файл после каждого крупного шага и открывайте его в PowerPoint. Ошибку в одном слайде найти легко, а в отчёте на двести слайдов почти невозможно.

Когда стоит писать скрипт, а когда нет?

Где автоматизация окупается?

Скрипт выгоден, когда одинаковые презентации нужно собирать регулярно: еженедельный отчёт по продажам, карточки товаров для каждого из сотни клиентов, сертификаты участникам, сводки из системы аналитики. Один раз потратили вечер на код, дальше каждый выпуск собирается за секунды и без ошибок копирования. Особенно это заметно, если данных много и они меняются каждый день.

Когда проще обойтись без кода?

Если презентация разовая, а главное в ней история и дизайн, программировать нет смысла. Код хорош для структуры и цифр, но придумать сюжет выступления и подобрать картинки он за вас не сможет. В таких случаях быстрее открыть редактор или сервис, который соберёт слайды по теме, и потратить время на смысл, а не на координаты в дюймах.

Хорошая проверка перед стартом проекта: посчитайте, сколько раз в месяц вы собираете один и тот же документ вручную. Один раз в квартал? Скорее всего, код не нужен. Каждую неделю, да ещё с цифрами из нескольких источников? Тогда скрипт на сорок строк вернёт потраченный вечер уже через месяц, а коллеги перестанут ловить опечатки в цифрах, перенесённых руками из таблицы.