pypdf: возможности, ограничения, установка и работа с PDF из Python

pypdf — не программа для чтения PDF с окнами, панелями и кнопками, а свободная Python-библиотека для программной обработки документов. Она подходит, когда PDF нужно разбирать, объединять, делить, поворачивать, обрезать, дополнять аннотациями, читать формы, извлекать текст и метаданные или защищать паролем прямо из собственного скрипта, сервиса либо конвейера обработки. Актуальная на дату этого обзора версия 6.18.1 опубликована 11 сентября 2026 года; пакет относится к стабильным, распространяется по BSD-3-Clause и требует Python 3.9 или новее. При этом важно сразу отделить pypdf от прежнего PyPDF2: современный поддерживаемый проект называется именно pypdf, строчными буквами и без цифры.

Скачать PyPDF

Безопасный обычный путь получения pypdf — установка опубликованного пакета из Python Package Index через пакетный менеджер. Для стандартной установки достаточно команды python -m pip install pypdf. На PyPI для версии 6.18.1 опубликованы исходный архив и универсальный wheel py3-none-any, поэтому у самого pypdf нет отдельных «редакций для Windows», «версии для macOS» или собственного Linux-инсталлятора. Если окружение управляется Anaconda, официальная документация также указывает канал conda-forge.

Перед установкой полезно проверить, какой именно интерпретатор запускает команда Python и какой pip с ним связан. Это особенно важно на системах с несколькими версиями Python: пакет может успешно установиться в одно окружение, а скрипт запускаться из другого. Для воспроизводимого проекта разумно создать виртуальное окружение, установить pypdf внутрь него и зафиксировать используемую версию в файле зависимостей проекта. Разработческая сборка из Git-репозитория существует, но это не лучший выбор для обычной эксплуатации: стабильный выпуск с PyPI проще отслеживать и откатывать.

Базовая установка сознательно минимальна. Для PDF с AES-шифрованием документация предлагает дополнительный набор зависимостей pypdf[crypto]; для извлечения изображений — pypdf[image], который добавляет Pillow; все поддерживаемые дополнительные зависимости можно запросить через pypdf[full]. Для декодирования JBIG2-изображений нужен отдельный системный пакет jbig2dec, поэтому такой сценарий уже зависит не только от Python-окружения. Случайные сайты с перепакованными архивами pypdf не дают преимуществ перед официальной публикацией пакета и усложняют проверку происхождения версии.

Что такое PyPDF

pypdf — свободная pure-Python библиотека, ориентированная на разработчиков. Её ядро решает задачи, требующие понимания внутренней структуры PDF: чтение объектов документа, выбор и перенос страниц, объединение файлов, изменение геометрии страницы, извлечение текста и метаданных, работа с частью интерактивных объектов, а также шифрование и расшифрование. Это библиотека внутри приложения пользователя, а не самостоятельная программа, поэтому «запустить pypdf» двойным щелчком и получить окно просмотра невозможно.

История названия важна для поиска документации и зависимостей. Исходный проект pyPdf появился в 2005 году. Позже возник PyPDF2, который многие годы был самым узнаваемым именем этой ветки. В 2022 году обслуживание PyPDF2 возобновилось, а выпуск 3.1.0 в декабре 2022 года перенёс активную линию обратно в пакет pypdf. Официальный журнал изменений прямо указывал, что PyPDF2 больше не будет получать обновления и пользователям следует переходить на pypdf. Поэтому статьи, где «PyPDF», «PyPDF2», PyPDF3 и PyPDF4 описываются как взаимозаменяемые актуальные пакеты, смешивают разные поколения.

Первоначальный автор проекта — Mathieu Fenniak; сейчас разработка ведётся как открытый проект организации py-pdf при участии сообщества и активных сопровождающих. На PyPI пакет классифицирован как стабильный и предназначенный для разработчиков. Его позиционирование также очерчено официально: pypdf занимается манипуляциями с PDF, извлечением данных и защитой PDF, но не стремится стать OCR-системой, конвертером DOCX/HTML или полноценным настольным редактором.

Хронология развития и поддержки

Ключевая точка для современных проектов — конец 2022 года: PyPDF2 3.0.0 сменился pypdf 3.1.0, причём для этого конкретного перехода изменение имени пакета было главным различием. После этого pypdf получил дальнейшие улучшения извлечения текста, AES, аннотаций, меток страниц, устойчивости и производительности. К 2026 году ветка 6.x активно обновляется: только в релизе 6.18.1 добавлены дополнительные ограничения при восстановлении FlateDecode, лимиты для таблиц ширин шрифтов и длины токенов, а также исправления visitor_text, меток страниц и FreeText.

Практический вывод из такой истории прост: для нового кода надо ориентироваться на документацию и API текущего pypdf, а не переносить примеры PyPDF2 без проверки. Политика безопасности проекта предусматривает исправления в последней версии, поэтому на сервере, который принимает PDF от внешних пользователей, длительное удержание старой ветки без обновлений повышает риск столкнуться с уже исправленными проблемами разбора вредоносно сформированных файлов.

Основные функции PyPDF

Чтение, сборка и перестановка страниц

Базовая модель строится вокруг PdfReader и PdfWriter. Reader открывает файл или seek-совместимый поток, предоставляет страницы и объекты документа; Writer формирует новый PDF, добавляет и вставляет страницы, может клонировать исходный документ и сохранять результат. На этой базе строятся разбиение одного документа на несколько файлов, извлечение выбранного диапазона, объединение нескольких источников и перестановка страниц. Для пакетных операций это удобнее GUI, потому что правило выбора страниц можно выразить кодом и повторить на сотнях файлов без ручных кликов.

Поворот, масштабирование, обрезка и наложение

PageObject поддерживает поворот страниц, масштабирование и матричные преобразования. Можно изменить размеры страницы, объединить содержимое двух страниц, наложить одну поверх другой либо под неё, применить сдвиг, поворот или масштаб к добавляемому слою. На этом же механизме строятся штампы и водяные знаки, когда страница-шаблон объединяется с содержимым целевого документа.

Обрезку надо трактовать точно. Изменение cropbox или другого видимого прямоугольника не обязательно физически удаляет контент, оказавшийся за границей отображения. Официальная документация специально предупреждает: скрытое обрезкой содержимое может оставаться в PDF и быть восстановлено. Поэтому crop не следует использовать как средство безопасного удаления конфиденциальных фрагментов. Если цель — редактирование с гарантированным уничтожением данных, нужен инструмент с подтверждённой функцией редактирования/redaction и контроль итоговой структуры.

Извлечение текста и работа с координатами

Метод extract_text извлекает текстовые операции из содержимого страницы. Помимо обычного режима есть layout-режим, который старается приблизить горизонтальное расположение текста к исходной странице. Можно ограничивать учитываемые ориентации текста и подключать visitor-функции, получающие текстовые фрагменты, матрицы преобразования, шрифт и размер. Это позволяет, например, отделять основной текст от колонтитулов по координатам или собирать собственный анализатор областей страницы.

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

Скан без текстового слоя — другой класс задачи. pypdf не выполняет OCR и не извлекает текст из пикселей. Если сканер уже добавил скрытый текстовый слой, библиотека может прочитать его, но качество этого текста определяется предыдущим OCR. Для самостоятельного распознавания разумнее использовать специализированное решение; на сайте есть отдельный обзор ABBYY FineReader, который относится именно к классу OCR-программ, а не к Python-библиотекам разбора PDF.

Метаданные, закладки, метки страниц и параметры просмотра

PdfReader предоставляет метаданные, XMP, outline, именованные назначения и метки страниц; PdfWriter умеет создавать и менять дерево закладок. При сборке многочастного документа это позволяет сохранить навигацию, а не ограничиваться механической склейкой страниц.

Формы, аннотации и вложения

pypdf читает поля AcroForm, обновляет их значения и поддерживает flatten-сценарий. Для типичного заполнения документация рекомендует auto_regenerate=False. Через API также добавляются распространённые аннотации — FreeText, заметки, линии, фигуры, ссылки и выделения — и файловые вложения. Это программное управление координатами и свойствами, а не визуальный редактор; сложные XFA-формы нельзя автоматически считать полностью совместимыми.

Для аннотаций библиотека предоставляет классы свободного текста, текстовой заметки, линий, полилиний, прямоугольников, эллипсов, многоугольников, ссылок, всплывающих окон и выделения. Есть API для добавления файлов-вложений. Это даёт программный контроль, но не интерактивный редактор: координаты, прямоугольники и свойства аннотации задаёт код. Если пользователю нужно мышью выделять фрагменты и визуально редактировать PDF, настольный редактор будет уместнее.

Извлечение изображений

Через коллекцию images страницы можно получать встроенные растровые изображения; для удобного декодирования и сохранения нужна дополнительная зависимость Pillow. Изображения могут встречаться не только непосредственно на странице, но и внутри других PDF-объектов, например штамп-аннотаций. Документация также предупреждает, что исходные имена вложенных изображений могут содержать произвольные символы, поэтому их нельзя без фильтрации использовать как пути файлов при обработке недоверенных документов.

Шифрование и расшифрование

Здесь есть важная настройка безопасности: если алгоритм не указан явно, ради совместимости может использоваться RC4, который официальная документация считает небезопасным и рекомендует заменять AES. В примерах pypdf отдельно показывается явный выбор AES-256-R5. Шифрование паролем не следует путать с электронной подписью: криптографическое подписание PDF в официальный текущий scope pypdf не входит.

Интерфейс и удобство использования

На стартовом уровне API достаточно прямолинеен: открыть Reader, взять страницы, создать Writer, добавить нужные страницы и записать новый файл. Порог заметно растёт при формах, ссылках, вложениях, шрифтах, нестандартных кодировках и повреждённых PDF, потому что тогда приходится разбираться с моделью объектов стандарта. Режим strict по умолчанию выключен: библиотека старается исправлять часть отклонений и выдавать предупреждения, тогда как strict=True делает некоторые проблемы фатальными. Это полезная развилка для production-конвейера: «мягкий» разбор повышает совместимость, а строгий помогает выявлять некорректные входы.

Документация подробно разделена по задачам и содержит API-справочник, но pypdf всё равно остаётся программным компонентом. Если цель — просто открыть PDF, искать текст и печатать, интерфейс читателя вроде Foxit Reader или Sumatra PDF снимает необходимость писать код. Если нужна ручная правка объектов страницы, форм и содержимого, ближе по модели будет полноценный редактор, например описанный на сайте Adobe Acrobat Pro.

Поддерживаемые форматы и совместимость

Основной входной и выходной формат pypdf — PDF. PdfReader принимает путь либо поток, который поддерживает операции чтения и позиционирования, поэтому библиотеку можно использовать с BytesIO и объектами, полученными из базы данных или облачного SDK. PdfWriter пишет в путь или file-like объект. Это удобная интеграционная граница: pypdf не требует, чтобы документ обязательно лежал постоянным файлом на локальном диске.

Поддержка PDF охватывает многие конструкции разных поколений стандарта, включая content streams, cross-reference streams, object streams, CMaps и AES. Однако «PDF 2.0» нельзя понимать как обещание реализовать каждый необязательный механизм стандарта. Официальная таблица поддержки прямо предупреждает, что отдельные функции могут отсутствовать. Особенно важно не приписывать pypdf полноценную цифровую подпись, универсальный incremental-update workflow, визуальную редактуру текста или гарантированную работу со всеми XFA-сценариями.

Форматы DOCX, HTML, ODT и электронные таблицы pypdf сам в PDF не конвертирует и обратно их не экспортирует. Генерация сложного PDF с нуля также не является его основной задачей: можно создать пустую страницу и собирать PDF-объекты, но для отчётов, счетов и многостраничной вёрстки удобнее специализированный генератор. Если задача начинается с редактируемого офисного документа, практичнее сначала сформировать PDF средствами офисного ПО; например, LibreOffice относится к другому классу инструментов и умеет экспортировать документы в PDF через пользовательский интерфейс.

Карта критических зависимостей

Производительность и стабильность

Самый показательный риск — извлечение текста. Чтобы разобрать текст страницы, нужно обработать её content stream целиком. Документация приводила редкий, но практический пример, когда около 300 МБ несжатого content stream потребовало порядка 10 ГБ RAM. Это не типичный офисный PDF, однако сервер, принимающий неизвестные файлы, должен иметь ограничения размера, тайм-ауты и обработку исключений. В современных версиях pypdf дополнительно появились глобальные лимиты на потенциально опасные размеры и число структур, что уменьшает риск чрезмерного потребления ресурсов на специально сформированных входах.

Для повреждённых PDF режим strict=False повышает терпимость к некоторым исправимым отклонениям, но это не гарантия восстановления любого файла. pypdf умеет обходить ряд некорректных структур, однако специализированные инструменты на базе qpdf могут быть предпочтительнее, когда главная задача — ремонт тяжело повреждённых PDF или линейризация. Стабильность приложения также зависит от того, ловит ли код PdfReadError, ошибки декодирования изображений и другие ожидаемые исключения, вместо того чтобы позволять одному плохому файлу завершить весь batch.

Лицензирование и версии

pypdf распространяется по лицензии BSD-3-Clause. У библиотеки нет отдельной платной редакции, подписки, пробного периода, водяного знака или лимита страниц. Она может использоваться в коммерческом ПО при соблюдении условий BSD-лицензии, включая сохранение требуемых уведомлений. При этом дополнительные зависимости имеют собственные лицензии, и юридическую проверку поставки продукта следует проводить по полному дереву зависимостей, а не только по pypdf.

PyPDF2 не является «бесплатной редакцией pypdf» и не существует параллельно как рекомендуемая современная ветка. Это прежнее имя активной линии, поддержка которой была перенесена в pypdf. Аналогично PyPDF3 и PyPDF4 — отдельные исторические попытки развития и не должны подменять пакет pypdf в новом проекте.

Системные требования

Python и операционная система

Официальное минимальное требование для pypdf 6.18.1 — Python 3.9. PyPI перечисляет Python 3.9, 3.10, 3.11, 3.12, 3.13 и 3.14, а сам пакет имеет классификатор OS Independent. Универсальный wheel py3-none-any подтверждает, что базовая библиотека не привязана к конкретной архитектуре Windows, macOS или Linux. Отдельного требования к процессору, видеокарте или графическому окружению нет.

Дополнительные сценарии

Для AES следует установить crypto extra, для извлечения изображений — image extra с Pillow. JBIG2 требует jbig2dec на уровне операционной системы. Официальная документация не задаёт универсальный минимум RAM и диска, поэтому придумывать цифру для «системных требований» некорректно: потребление памяти зависит от внутренней структуры PDF и конкретной операции. На сервере лимиты ресурсов следует определять нагрузочным тестированием на своих документах, учитывая, что распаковка потоков может многократно увеличить объём данных относительно файла на диске.

Среда разработки

Преимущества и недостатки PyPDF

Плюсы и минусы

Сравнение с аналогами

PyMuPDF шире в задачах визуализации: умеет рендерить страницы, извлекать текст и изображения, работать с большим набором типов документов и имеет OCR-путь для изображений страницы. При выборе для закрытого коммерческого продукта нужно отдельно учитывать его AGPL/коммерческую модель лицензирования. pypdf не конкурирует с PyMuPDF как движок просмотра; его сильная сторона — программное изменение структуры PDF без обязательного рендеринга.

Sumatra PDF сравним с pypdf только на уровне пользовательской цели «работать с PDF». Это разные слои. Sumatra PDF — готовый Windows-просмотрщик с интерфейсом и поддержкой PDF, электронных книг, DjVu, XPS, изображений и других форматов. pypdf — модуль для Python-кода. В текущей стабильной Sumatra PDF основной сценарий остаётся просмотр, а в ветке pre-release 3.7 развиваются консольные инструменты конвертации и изменения документов. Если задача человека — читать документ, pypdf будет избыточным и неудобным; если сервер должен автоматически собрать тысячу PDF по правилу, GUI Sumatra не заменит библиотечный API.

Паспорт обратимости операций

Инструкция по установке

Установка через pip

1. Установите поддерживаемый Python 3.9 или новее и убедитесь, что команда python —version указывает на ожидаемый интерпретатор.
2. Создайте виртуальное окружение проекта средствами Python и активируйте его. Это не строгое требование pypdf, но изолирует зависимости приложения.
3. Обновите pip в этом окружении, если корпоративная политика разрешает обновление установщика пакетов.
4. Выполните python -m pip install pypdf. Для AES используйте python -m pip install «pypdf[crypto]», для извлечения изображений — python -m pip install «pypdf[image]».
5. Проверьте установку командой python -m pip show pypdf и коротким запуском Python, который импортирует pypdf и выводит номер версии.
6. Зафиксируйте рабочую версию в зависимостях проекта и прогоните свои PDF-тесты до развёртывания.

Первый запуск без риска для исходника

1. Возьмите тестовый PDF, копию которого можно безболезненно изменить.
2. Откройте его через PdfReader и получите количество страниц. На этом этапе файл только читается.
3. Создайте PdfWriter, добавьте одну или несколько страниц Reader и укажите новое имя выходного файла.
4. Запишите результат в отдельный PDF, не используя имя исходника.
5. Откройте выходной файл обычным PDF-просмотрщиком и проверьте число страниц, ориентацию, текст, ссылки и форму, если они были в исходнике.

Обновление с запасным выходом

1. Зафиксируйте текущую рабочую версию и результаты тестов.
2. Создайте отдельное виртуальное окружение с новой версией pypdf, а не обновляйте production-среду на месте.
3. Прогоните тот же корпус PDF и сравните не только отсутствие исключений, но и ключевые свойства результата: страницы, текст, формы, ссылки и шифрование.
4. Если поведение приемлемо, обновите ограничение версии и разверните сборку обычным процессом приложения.
5. Если появились несовместимости, откатите зависимость к прежней версии, не меняя исходные документы.

Безопасное удаление пакета

Если pypdf установлен через pip, официальный механизм удаления — python -m pip uninstall pypdf в том же окружении. Сначала активируйте нужный virtualenv и проверьте пакет через python -m pip show pypdf, чтобы не удалить зависимость из другого интерпретатора. Удаление библиотеки не затрагивает созданные PDF; перед ним достаточно сохранить исходный код и файл зависимостей проекта.

Практические кейсы

Собрать один PDF из выбранных страниц нескольких файлов

Цель: собрать выбранные страницы нескольких PDF. Подготовка: список файлов и диапазонов. Шаги: открыть источники через PdfReader, создать PdfWriter, добавить нужные страницы или append-диапазоны и записать новый файл. Проверка: число и порядок страниц плюс открытие результата в независимом viewer. Ограничение: формы, закладки и внутренние ссылки требуют отдельной проверки переноса.

Извлечь текст для индексации

Цель: получить текст для индексации. Подготовка: проверить, что исходник содержит выделяемый текст. Шаги: вызвать extract_text для страниц; при необходимости использовать layout или visitor для координатной фильтрации. Проверка: сопоставить несколько контрольных фрагментов. Ограничение: скан без текстового слоя требует OCR, а таблицы могут потерять структуру.

Заполнить AcroForm и сохранить копию

Цель: заполнить AcroForm. Подготовка: получить точные имена через get_fields. Шаги: перенести документ в Writer, обновить значения с auto_regenerate=False и сохранить копию. Проверка: открыть результат в целевом PDF-viewer. Ограничение: XFA и сложные иерархии полей могут потребовать другого инструмента.

Добавить пароль AES к готовому PDF

Цель: защитить PDF паролем. Подготовка: установить crypto extra. Шаги: клонировать документ в Writer, вызвать encrypt с явным AES-алгоритмом и записать новый файл. Проверка: неверный пароль не открывает содержимое, правильный работает. Ограничение: это шифрование, а не электронная подпись.

Извлечь встроенные изображения с безопасными именами

Цель: извлечь встроенные изображения. Подготовка: установить image extra, при необходимости jbig2dec. Шаги: пройти по page.images и сохранять ресурсы под собственными безопасными именами. Проверка: пересчитать и открыть выборку файлов. Ограничение: ошибки отдельных ресурсов нужно перехватывать, чтобы не останавливать весь batch.

Навигатор по сбоям

• ImportError. Сверьте, какой Python запускает скрипт, и установите пакет через python -m pip в то же окружение.
• Ошибка чтения PDF. Зафиксируйте исключение и версию, оставьте штатный strict=False и не отключайте защитные лимиты без диагностики файла.
• Плохой порядок extract_text. Сравните plain и layout; если страница является изображением, переходите к OCR.
• Пропали поля формы. Проверьте перенос AcroForm и используйте append вместо предположения, что add_page копирует структуру полей.
• Высокое потребление памяти. Найдите проблемную страницу, оцените распакованный content stream и ограничьте ресурсы процесса.

Часто задаваемые вопросы

Нужно ли удалять PyPDF2 перед установкой pypdf?

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

Можно ли pypdf использовать без интернета?

Да. После установки локальная обработка локальных файлов не требует сервиса pypdf или аккаунта. Интернет понадобится только если само приложение получает PDF из сети, обращается к облачному хранилищу или устанавливает/обновляет пакеты.

Поддерживает ли pypdf электронные подписи?

Полноценная криптографическая цифровая подпись не входит в текущий заявленный scope библиотеки. Шифрование PDF паролем и расшифрование — отдельные функции и не дают свойства электронной подписи.

Насколько безопасно обрабатывать неизвестные PDF?

Ни одна библиотека разбора сложного формата не должна запускаться без ограничений ресурсов на недоверенном вводе. pypdf 6.x содержит лимиты на размеры потоков, глубину и количество отдельных структур, а security policy рекомендует использовать актуальную версию. В веб-сервисе дополнительно нужны ограничения размера загрузки, тайм-аут, изоляция процесса и обработка исключений.

Какую альтернативу выбрать для визуальной склейки страниц?

Если программировать не хочется, удобнее настольный инструмент. Например, PDFsam Basic ориентирован именно на объединение, разделение, извлечение и поворот страниц через готовое приложение. pypdf сильнее там, где правила должны исполняться автоматически внутри Python.

Вывод

Выбирать pypdf не стоит, если нужен готовый графический просмотрщик, OCR сканов, визуальное редактирование текста страницы, универсальная конвертация офисных форматов или цифровая подпись. Для чтения на Windows логичнее Sumatra PDF или другой viewer; для рендеринга и более широких документных операций стоит сравнить PyMuPDF; для ремонта, линейризации и возможностей qpdf — pikepdf; для ручной работы с PDF — настольный редактор. Сильная сторона pypdf не в том, что он заменяет все эти классы программ, а в том, что даёт прозрачный, переносимый и лицензируемый по BSD программный слой для автоматизации PDF внутри Python.