PyMuPDF: возможности, лицензия, форматы и практическая работа с PDF в Python

PyMuPDF занимает необычное место среди инструментов для PDF: это не программа, которую запускают двойным щелчком ради чтения документа, а Python-библиотека для программного доступа к движку MuPDF. Она ориентирована на извлечение текста и таблиц, рендеринг страниц, изменение структуры PDF, аннотации, формы, шифрование, редактирование содержимого и подготовку документов для дальнейшего анализа. На 12 сентября 2026 года актуальная стабильная версия — 1.28.2, выпущенная 6 августа 2026 года; официальная документация уже описывает именно эту ветку. Важно не путать базовый PyMuPDF с отдельными продуктами PyMuPDF Pro и PyMuPDF4LLM: они расширяют сценарии работы, но имеют собственное назначение и условия лицензирования.

ПараметрАктуальное состояние
ТипPython-библиотека и привязки к движку MuPDF
Разработчик и сопровождениеArtifex Software, Inc.; PyMuPDF и MuPDF поддерживаются Artifex
Текущая версия1.28.2 от 6 августа 2026 года
Python3.10 и новее для текущего пакета на PyPI
Основные ОСWindows, Linux, macOS; публикуются готовые wheels для нескольких архитектур
Ключевые задачиИзвлечение данных, рендеринг, создание и изменение PDF, конвертация, OCR через Tesseract
ЛицензияGNU AGPL v3 или коммерческая лицензия Artifex
Графический интерфейсНет; работа через Python API, скрипты, IDE, ноутбуки и собственные приложения
Облако и аккаунтДля базовой локальной обработки не требуются; коммерческие расширения лицензируются отдельно

Скачать PyMuPDF

Бесплатно
В реестре российского ПО
Чистая установка

Новейшая версия для Виндовс, macOS и Линукс. Удобный редактор PDF под российские реалии.

⬇ Скачать PDF Commander бесплатно

⬇ Скачать PyMuPDF

Безопасный стандартный путь получения PyMuPDF — установка пакета с именем pymupdf через Python Package Index средствами pip. Для обычного проекта разумно сначала создать отдельное виртуальное окружение, обновить pip, а затем установить пакет командой python -m pip install —upgrade pymupdf. Такой подход отделяет зависимости проекта от системного Python и упрощает обновление или удаление библиотеки.

На дату проверки PyPI публикует версию 1.28.2 как актуальную. Для неё доступны готовые бинарные wheels, в том числе для Windows x86, x86-64 и ARM64, Linux x86-64 и ARM64 в поддерживаемых manylinux-вариантах, macOS на Intel и Apple Silicon. Для macOS текущие колёса указывают минимальные уровни 10.15 для Intel и 11.0 для ARM64. Есть также отдельные сборки для некоторых сред musl и WebAssembly/Pyodide. Если подходящего wheel нет, pip пытается собрать пакет из исходников, что уже требует C/C++-инструментов и заметно сложнее обычной установки.

Что такое PyMuPDF

PyMuPDF — высокоуровневый Python API к MuPDF, нативному движку рендеринга и обработки документов. Библиотека предоставляет объектную модель документа, страниц, аннотаций, форм, изображений, геометрии и низкоуровневых PDF-объектов. Поэтому она находится ближе к SDK, чем к привычному PDF-редактору: пользователь не получает готовое окно с панелью инструментов, зато разработчик может встроить нужные операции в скрипт, сервис, настольное приложение, конвейер обработки или аналитическую систему.

Текущее сопровождение осуществляет Artifex Software. Проект не снят с поддержки: в 2026 году выходили несколько веток 1.27 и 1.28, а версия 1.28.2 синхронизирована с MuPDF 1.28.2. На PyPI проект помечен как Production/Stable. Это существенно отличает PyMuPDF от старых примеров в интернете, где встречается импорт fitz, устаревшие имена методов или ограничения прошлых выпусков.

Базовый PyMuPDF также нельзя смешивать с PyMuPDF Pro. Pro — набор коммерческих расширений, который добавляет обработку офисных форматов, включая DOC/DOCX, XLS/XLSX, PPT/PPTX и HWP/HWPX, а также коммерческую составляющую для связанных LLM/RAG-сценариев. Базовая библиотека сама по себе остаётся универсальным инструментом прежде всего для PDF и форматов, поддерживаемых MuPDF. PyMuPDF4LLM — ещё один отдельный пакет, заточенный под выдачу Markdown, JSON и подготовку контента для RAG; он использует экосистему PyMuPDF, но не является новым именем самой библиотеки.

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

Извлечение текста, блоков и структуры страницы

Page.get_text() умеет возвращать текст не только одной строкой. Доступны представления в виде обычного текста, слов с координатами, блоков, HTML/XHTML, XML, а также словарных и JSON-подобных структур, где сохраняются сведения о блоках, строках, фрагментах и геометрии. Это позволяет выбирать уровень детализации под задачу: для поиска достаточно текста, для восстановления макета нужны координаты слов и блоков, а для анализа шрифтов и фрагментов полезны структурированные варианты.

Таблицы и поиск

Метод Page.find_tables() предназначен для обнаружения табличных областей и извлечения их содержимого. В версии 1.28.2 для него появились дополнительные параметры use_layout, union и refine, а разработчики отдельно отметили улучшение скорости. Возможность полезна для отчётов, счетов и ведомостей, но результат всё равно зависит от структуры исходного PDF: таблица, нарисованная как произвольный набор координат и линий, может требовать настройки стратегии и последующей проверки.

Рендеринг страниц и извлечение изображений

Page.get_pixmap() растеризует страницу с заданным масштабом или разрешением, а Page.get_svg_image() формирует SVG-представление. Изображения, встроенные в PDF, можно перечислять и извлекать отдельно. Такой набор подходит для генерации миниатюр, превью, подготовки страниц к компьютерному зрению, создания наборов данных и конвертации страниц в PNG или другие поддерживаемые растровые форматы.

Создание, сборка и изменение PDF

PyMuPDF способен создавать пустые документы и страницы, вставлять текст, HTML-блоки, изображения, ссылки и векторную графику. Для более сложной генерации существует Story, позволяющий раскладывать HTML/CSS-содержимое по страницам через DocumentWriter. Библиотека умеет копировать диапазоны страниц между документами, объединять и разбивать PDF, переставлять листы, менять размеры и повороты, накладывать страницу одного PDF на страницу другого.

Начиная с 1.28.0 обычный Document.save() при работе с документом не в формате PDF сохраняет результат как PDF. Это упрощает конвейеры «открыть поддерживаемый формат — обработать — получить PDF», но не превращает базовую библиотеку в полноценный импортёр Microsoft Office. Форматы Word, Excel и PowerPoint относятся к PyMuPDF Pro.

Аннотации, формы, ссылки и вложения

Для PDF доступны текстовые заметки, выделение, подчёркивание, зачёркивание, фигуры, линии, штампы, файловые вложения и redaction-аннотации. Можно читать и изменять многие поля AcroForm: текстовые поля, кнопки, флажки, списки, combo box и группы radio button. Ограничение важно: поля цифровой подписи доступны для чтения состояния, но PyMuPDF не создаёт и не обновляет подписи и не выполняет криптографическое подписание PDF.

Редактирование содержимого, redaction и безопасность PDF

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

Поддерживается шифрование PDF паролями, включая AES-256, настройка прав печати, копирования, аннотирования и других действий, а также открытие защищённых документов после аутентификации. Document.save() управляет инкрементальным сохранением, очисткой неиспользуемых объектов, deflate-сжатием, object streams и linearization для последовательной загрузки через сеть. Есть и низкоуровневый доступ к xref и stream-объектам, что полезно для диагностики и специализированных преобразований.

OCR через Tesseract

OCR встроен в API, но движок распознавания не является частью самодостаточной установки PyMuPDF: требуется Tesseract и его языковые данные. Page.get_textpage_ocr() может распознавать всю страницу или области без уже читаемого текста, а Pixmap умеет формировать PDF с OCR-слоем. Для русского языка нужен соответствующий пакет данных Tesseract и корректно найденный каталог tessdata.

Официальная документация предупреждает, что OCR примерно на три порядка медленнее обычного извлечения текста. Поэтому рациональная схема — сначала проверить наличие нормального текстового слоя и только при его отсутствии запускать распознавание. Полученный TextPage желательно переиспользовать для последующих поисков и извлечений, а не повторять OCR для одной страницы несколько раз.

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

У PyMuPDF нет собственного окна, меню, панелей или локализованного пользовательского интерфейса. Рабочая среда определяется самим разработчиком: терминал, VS Code, PyCharm, Jupyter, серверное приложение или собственный GUI. Поэтому «удобство» здесь означает ясность API, документации и объектной модели, а не расположение кнопок.

Базовая логика достаточно последовательна: Document открывает файл, страницы доступны по индексу, Page отвечает за содержимое и геометрию, Pixmap — за растровое представление, Annot и Widget — за аннотации и поля форм. Для типовых задач путь короткий: открыть документ, пройти по страницам, выполнить операцию, сохранить результат. Порог входа становится выше, когда нужны координатные системы PDF, матрицы преобразований, низкоуровневые объекты xref или точное понимание того, какие изменения можно сохранить инкрементально.

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

Базовый PyMuPDF открывает PDF, XPS, EPUB, MOBI, FB2, CBZ, SVG, TXT и Markdown, а также ряд растровых изображений, включая распространённые JPEG, PNG, BMP, GIF и TIFF. Для текстовых данных без надёжной сигнатуры типа может потребоваться явно указать filetype. Распознавание содержимого умеет во многих случаях определить формат независимо от расширения, но обычные текстовые форматы по своей природе неоднозначны.

Вывод также неодинаков для разных объектов. Страницу можно растеризовать или получить в SVG, изображения — сохранить в поддерживаемые Pixmap-форматы, текст — извлечь в нескольких структурных представлениях. С версии 1.28.0 Document.save() сохраняет открытые документы не в формате PDF в PDF. Это удобный путь конвертации, но не эквивалент офисному пакету с сохранением редактируемой структуры исходного DOCX или XLSX.

Если нужны Microsoft Office и HWP/HWPX, это зона PyMuPDF Pro, а не базовой AGPL-редакции. Pro заявлен для Windows x86-64, Linux x86-64 на glibc, macOS x86-64 и macOS ARM64. То есть наличие базового wheel PyMuPDF для другой архитектуры ещё не означает, что на ней доступно коммерческое расширение.

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

Для больших документов полезно обрабатывать страницы последовательно и не создавать без необходимости огромные промежуточные объекты. Document.tobytes() формирует итоговый PDF в памяти, поэтому при сотнях мегабайт исходных данных предпочтительнее сохранение в файл или поток с контролируемым жизненным циклом. Растеризация на высоком DPI также быстро увеличивает потребление памяти, поскольку размер Pixmap пропорционален площади изображения и числу каналов.

Критическое ограничение многопоточности: официальная документация прямо указывает, что PyMuPDF не поддерживает параллельную работу через несколько threads; это может привести к неправильному поведению или аварийному завершению Python. Для распараллеливания страниц предлагается multiprocessing. При таком подходе каждый процесс открывает документ самостоятельно и получает свой диапазон страниц, поскольку объект Document нельзя безопасно передать как общий изменяемый ресурс.

Повреждённые PDF могут быть восстановлены движком при открытии или сохранении. Версия 1.27.0 добавила параметр raise_on_repair, позволяющий превратить факт ремонта при сохранении в исключение: это полезно в контролируемых конвейерах, где незаметное восстановление способно изменить данные. Инкрементальная запись доступна не во всех случаях; перед её использованием есть метод can_save_incrementally(). Для подписанных документов перезапись в новый файл может нарушить существующие проверяемые подписи, поэтому режим сохранения нужно выбирать осознанно.

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

ЗависимостьКогда нужнаЧто произойдёт без неёПрактический вывод
CPython 3.10+Всегда для актуального пакетаТекущая версия не установится на более старую ветку PythonВерсию Python фиксировать в окружении проекта
MuPDFВсегдаЭто базовый движок PyMuPDFПри стандартном wheel не требуется отдельная ручная установка MuPDF
Tesseract и tessdataТолько OCRРаспознавание сканов недоступно, обычное извлечение продолжает работатьЯзыковые пакеты ставить только для нужных языков
PillowМетоды pil_save и pil_tobytesОстальная работа Pixmap не исчезаетНе добавлять зависимость, если интеграция с Pillow не нужна
fontToolsDocument.subset_fonts()Нельзя использовать конкретную операцию подмножества шрифтовПодключать для генерации и оптимизации, где это требуется
PyMuPDF ProOffice/HWP и коммерческие расширенияБазовый PyMuPDF не откроет DOCX/XLSX/PPTX как заявленные Pro-форматыНе закладывать офисный импорт в Community-сценарий
ИнтернетУстановка, обновление, получение коммерческой лицензииУже установленная локальная обработка обычных файлов не требует облакаДля закрытого контура заранее подготовить wheels и зависимости

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

PyMuPDF и MuPDF распространяются по двойной модели: GNU AGPL v3 либо коммерческая лицензия Artifex. Это не схема «бесплатно для любого использования с платной техподдержкой». AGPL накладывает существенные обязательства на распространение и сетевое предоставление производного приложения. На официальной странице Artifex прямо указано, что если организация не может соблюдать требования AGPL, требуется коммерческая лицензия.

Для закрытого продукта, OEM-встраивания или SaaS выбор лицензии нужно решать до внедрения библиотеки в архитектуру. Artifex отдельно подчёркивает сценарии серверного приложения: использование AGPL-компонента в сетевом сервисе нельзя автоматически считать «внутренним бесплатным использованием». Условия конкретного проекта лучше сверять с текстом лицензии и юридической службой; обзор программного продукта не заменяет правовую консультацию.

Фиксированной публичной цены коммерческой лицензии в проверенных официальных материалах нет: Artifex предлагает обращаться в отдел продаж и подбирает условия под способ распространения. Поэтому корректно говорить не о «стоимости PyMuPDF в месяц», а о бесплатной AGPL-модели при полном соблюдении её условий и отдельно согласуемом коммерческом договоре.

Базовый пакет не требует регистрации, активации аккаунта или пробного периода для установки под AGPL. PyMuPDF Pro, напротив, является коммерческим продуктом без AGPL-варианта. Официальная страница Pro разрешает бесплатную оценку с ограничением до 3 страниц; trial key снимает этот лимит на срок до 60 дней. Это отдельный продуктовый слой, и его пробный режим не меняет условия базового PyMuPDF.

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

Период или версияИзменениеЧто это значит сейчас
Исторические версииОсновное имя импорта было fitzСтарые примеры встречаются часто, но в новом коде лучше использовать pymupdf
С 1.24.0Современная документация рекомендует import pymupdfСнижается риск конфликта с посторонним пакетом fitz
1.27.0Добавлен raise_on_repair при сохраненииКонвейер может явно реагировать на восстановление проблемного PDF
1.28.0, 29 июня 2026Переход на MuPDF 1.28.0; документы не в формате PDF можно сохранять через Document.save() в PDF; добавлены archive и apply_cssРасширена конвертация и работа с архивными ресурсами
1.28.2, 6 августа 2026MuPDF 1.28.2, предупреждение для legacy-import fitz, улучшения find_tablesЭто актуальный релиз на дату обзора

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

Python и общие требования

Метаданные актуального пакета 1.28.2 указывают Python 3.10 или новее. Это надёжнее использовать как минимальную границу, чем старые таблицы совместимости из предыдущих релизов. Установка предполагает актуальный pip и предпочтительно виртуальное окружение. При наличии готового wheel обязательных внешних библиотек для базового набора функций нет.

Windows

PyPI публикует wheels для Windows x86, x86-64 и ARM64. Официальная документация предупреждает об отдельной проблеме с Python, установленным через Chocolatey: стандартные wheels PyMuPDF для такого окружения могут не подходить, и рекомендуется Python из обычного установщика python.org. При редких ошибках загрузки нативного модуля может понадобиться актуальный Microsoft Visual C++ Redistributable.

Linux

Текущие manylinux wheels 1.28.2 ориентируются на glibc 2.28+ для x86-64 и ARM64, а также существует musllinux-сборка для x86-64. Документация отдельно предупреждает: старые Linux-системы с более ранней glibc могут перестать принимать свежие wheels по мере обновления manylinux-баз. В таком случае остаются обновление ОС или локальная сборка. Для Linux ARM64 на musl, например некоторых конфигураций Alpine, поддержка остаётся проблемной.

macOS

Для 1.28.2 есть отдельные wheels для Intel и Apple Silicon. Метаданные PyPI указывают macOS 10.15+ для x86-64 и macOS 11.0+ для ARM64. Это важнее общих заявлений «поддерживается macOS», потому что на старом Mac бинарный пакет может не установиться.

Дополнительные компоненты

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

ОперацияОбратимостьЧто сохранить заранееКонтроль результата
Извлечение текста или изображенийНе меняет исходный документНичего сверх исходникаСравнить число страниц и выборочно сверить фрагменты
Перестановка, удаление и вставка страниц с сохранением в новый файлИсходник остаётся доступенОригинальный PDFПроверить порядок и количество страниц
Инкрементальное сохранение в тот же PDFИстория изменений может оставаться внутри файла, простой Undo отсутствуетРезервную копию до первой записиПовторно открыть файл и проверить can_save_incrementally до записи
Применённая redaction с последующим сохранениемУдалённое содержимое не следует считать восстанавливаемымОтдельный защищённый оригиналИскать удалённые строки и извлекать текст из итогового PDF
Очистка метаданных и garbage collectionПосле перезаписи потерянные объекты не восстанавливаются штатноОригинал и при необходимости экспорт метаданныхПовторно прочитать metadata и XML metadata
Изменение шифрования и паролейМожно задать новые параметры при очередном полном сохранении, если есть праваИсходные пароли и резервную копиюОткрыть итоговый файл с пользовательским и владельческим сценариями

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

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

— Широкий охват PDF-задач. Один API объединяет извлечение, рендеринг, изменение страниц, аннотации, формы, вложения, шифрование и низкоуровневый доступ.

— Нативный движок MuPDF. Рендеринг и многие тяжёлые операции выполняются не чистым Python-кодом.

— Точная геометрия. Можно получать координаты слов, блоков, изображений и областей поиска, что важно для автоматизации макетных документов.

— Локальная обработка. Базовые операции не требуют обязательной отправки документов в облачный сервис.

— OCR в едином API. После установки Tesseract распознанный текст можно искать и извлекать теми же механизмами TextPage.

Минусы

— Нет готового GUI. Для чтения или ручного редактирования одного документа библиотека неудобнее настольного приложения.

— AGPL требует внимания. Для закрытого ПО, SaaS и OEM нельзя автоматически считать бесплатную установку юридически нейтральной; может понадобиться коммерческая лицензия.

— Нет потокобезопасной многопоточности. Официально рекомендуемая масштабируемость строится через multiprocessing, что усложняет архитектуру.

— OCR требует внешнего Tesseract. Нужно установить движок, языковые пакеты и корректно настроить tessdata.

— Цифровое подписание PDF не реализовано. Signature widgets можно читать, но создание и криптографическое подписание не поддерживаются.

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

ИнструментТипСильная сторонаРедактирование PDFРендерингЛицензия
PyMuPDFPython + MuPDFУниверсальная обработка, геометрия, рендеринг, OCR-интеграцияШирокое программноеДаAGPL v3 или коммерческая
pypdfЧистый PythonСтруктурные операции без нативной зависимостиСтраницы, метаданные, шифрование, аннотации и другоеНе основной профильBSD-3-Clause
pikepdfPython + qpdfНизкоуровневое чтение, запись, ремонт и трансформация PDFСильное объектное и структурноеНе основной профильMPL-2.0
pdfplumberPython + pdfminer.sixСимволы, линии, таблицы и визуальная отладка извлеченияНе основной профильДля отладки и анализаMIT
Sumatra PDFНастольный просмотрщик для WindowsБыстрое интерактивное чтение PDF и других форматовНет сопоставимого программного API редактированияПоказывает страницы пользователюOpen source

PyMuPDF против pypdf. Актуальный pypdf остаётся чисто Python-библиотекой и распространяется по BSD-3-Clause. Его проще использовать там, где нежелательны нативные бинарные зависимости или AGPL, а задачи сводятся к структуре PDF, страницам, метаданным и стандартным преобразованиям. PyMuPDF обычно привлекательнее, когда нужны рендеринг, координатно точное извлечение, Pixmap, OCR-интеграция и более широкий набор визуальных операций.

PyMuPDF против Sumatra PDF. Это не прямые конкуренты. Sumatra PDF — конечное приложение для пользователя Windows: открыть файл, пролистать, найти текст, распечатать. PyMuPDF — строительный блок для разработчика. В рабочем процессе они могут сосуществовать: Python-скрипт готовит или проверяет PDF, а Sumatra PDF используется для быстрого визуального просмотра результата. Если нужен именно GUI с ручными правками, разумнее смотреть на PDF-XChange Editor или Adobe Acrobat Pro.

Для OCR без программирования ближе по пользовательскому сценарию ABBYY FineReader. Если задача — редактировать исходный офисный документ и затем экспортировать PDF, можно рассмотреть LibreOffice. Для простого пользовательского чтения альтернативой остаётся и Foxit Reader. Эти варианты не заменяют API PyMuPDF, но закрывают задачи, где программирование само по себе не даёт преимущества.

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

Windows

1. Установить поддерживаемый CPython 3.10 или новее; для предсказуемой совместимости PyMuPDF предпочтителен обычный дистрибутив Python, а не сборка через Chocolatey.

2. В каталоге проекта создать окружение командой py -m venv pymupdf-venv.

3. Активировать его командой .\pymupdf-venv\Scripts\activate.

4. Обновить установщик: python -m pip install —upgrade pip.

5. Установить библиотеку: python -m pip install —upgrade pymupdf.

6. Проверить импорт командой python -c «import pymupdf; print(pymupdf.__doc__)». В выводе должна появиться информация о PyMuPDF, а не ошибка модуля fitz.

Linux и macOS

Создайте окружение командой python -m venv pymupdf-venv, активируйте его через . pymupdf-venv/bin/activate, затем выполните python -m pip install —upgrade pip и python -m pip install —upgrade pymupdf. Если вместо wheel начинается сборка исходников, сначала проверьте архитектуру, glibc в Linux и минимальную версию macOS.

Добавление OCR

Установите Tesseract отдельно, добавьте языковые данные, определите каталог tessdata и передайте его OCR-функции либо задайте TESSDATA_PREFIX. Для русского используется язык rus; для нескольких языков коды объединяются через +. Проверку начинайте с одной известной страницы, сравнивая обычное извлечение и текст из get_textpage_ocr().

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

Для первого запуска достаточно открыть небольшой PDF через pymupdf.open(), прочитать page_count и извлечь текст первой страницы. После этого имеет смысл проверить сохранение в новый файл, не перезаписывая оригинал. Если библиотека больше не нужна и установлена в отдельном виртуальном окружении, самый чистый путь — деактивировать окружение и удалить его каталог вместе с зависимостями. Если окружение используется и для других пакетов, удалить только PyMuPDF можно через python -m pip uninstall pymupdf. Пользовательские PDF при этом не удаляются.

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

Если import pymupdf не находится, сверяйте интерпретатор и pip в одном окружении. Ошибка frontend после import fitz обычно указывает на посторонний пакет fitz. На старом Linux проверяйте glibc, на Windows при DLL-ошибках — Visual C++ Redistributable и разрядность. Для неработающего OCR прежде всего проверяйте traineddata и TESSDATA_PREFIX.

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

Извлечение текста и таблиц из отчёта

Цель. Получить из многостраничного отчёта текст для поиска и отдельно таблицы для последующей загрузки в аналитическую систему.

1. Открыть документ через pymupdf.open() и пройти страницы по порядку.

2. Для каждой страницы получить обычный текст и базовые блоки. Если текст пустой или явно неполный на сканированной странице, пометить её для OCR.

3. Запустить Page.find_tables() и сохранить найденные таблицы вместе с номером страницы и геометрией области.

4. Для помеченных сканов создать TextPage через get_textpage_ocr(), а затем извлечь текст с параметром textpage.

5. Собрать результат в структуру приложения, не меняя исходный PDF.

Проверка. Сопоставить количество обработанных страниц с page_count, найти несколько контрольных фраз и сравнить ключевые числа в таблицах с визуальным оригиналом.

Ограничение. Колонки и сложные таблицы могут потребовать дополнительной логики чтения. OCR также не восстанавливает исходные свойства шрифта и не гарантирует идеальный порядок текста.

Распознавание сканированного договора

Цель. Сделать скан пригодным для поиска по фамилии или реквизитам без обращения к облачному OCR.

1. На каждой странице сначала выполнить обычное get_text(). Если текст уже извлекается корректно, OCR пропустить.

2. Для страницы-изображения вызвать get_textpage_ocr() с нужным языком и разумным DPI.

3. Сохранить TextPage в переменной и использовать его для поиска и извлечения, не запуская повторное распознавание.

4. Если нужен новый PDF с OCR-слоем поверх исходных изображений, использовать OCR-возможности Pixmap и собрать страницы в отдельный документ.

Проверка. Искать заранее известные слова, проверить несколько числовых реквизитов и убедиться, что найденные координаты соответствуют строкам на странице.

Ограничение. Качество зависит от скана и Tesseract. Векторные чертежи OCR не распознаёт как текст, а распознанные символы получают упрощённые свойства GlyphLessFont.

Удаление конфиденциальной строки

Цель. Удалить заданный текст из выдаваемой копии PDF, а не просто закрыть его графическим прямоугольником.

1. Найти текст через search_for() и получить прямоугольники совпадений.

2. Добавить redaction-аннотации на каждую нужную область.

3. Применить Page.apply_redactions(), явно выбрав отношение к изображениям и векторной графике, если это важно.

4. Сохранить результат в новый файл с garbage collection, не уничтожая оригинал.

Проверка. Заново открыть результат, выполнить поиск удалённой строки и обычное извлечение текста. Дополнительно визуально проверить границы, чтобы не удалить соседний контент.

Ограничение. После применения redaction и корректного сохранения действие следует считать необратимым. Замена текста внутри redaction ограничена по форматированию; сложное оформление лучше вставлять отдельной операцией после удаления.

Контроль перед сохранением и передачей

— Сохранить исходный документ отдельно, если выполнялись redaction, очистка метаданных, удаление страниц или изменение шифрования.

— Повторно открыть итоговый PDF новым объектом Document, а не полагаться только на состояние в памяти.

— Сверить page_count, ключевые закладки, ссылки и формы, если они важны для процесса.

— После redaction выполнить текстовый поиск удалённых фрагментов и проверить выбранные области визуально.

— Для подписанного PDF заранее определить, допустимо ли полное сохранение: оно может повлиять на существующие цифровые подписи.

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

PyMuPDF и fitz — одно и то же?

fitz — историческое имя импорта PyMuPDF, которое оставлено как совместимый путь для старого кода. Для нового проекта рекомендуется import pymupdf. Отдельный пакет PyPI с именем fitz не является PyMuPDF и может ломать старый импорт.

Можно ли использовать PyMuPDF полностью офлайн?

После установки базовые операции с локальными файлами выполняются локально и не требуют аккаунта или облачного API. Интернет может понадобиться для первичной установки, обновления пакетов, получения документации или коммерческой лицензии. OCR через локальный Tesseract также может работать без отправки страниц в облако.

Почему текст извлекается в неправильном порядке?

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

Можно ли обрабатывать один документ в нескольких потоках?

Официальная документация не рекомендует multithreading для PyMuPDF и предупреждает о неправильном поведении вплоть до падения Python. Для параллельной обработки страниц используют multiprocessing, причём каждый процесс открывает файл самостоятельно.

Почему новый PDF после удаления страниц всё ещё большой?

В PDF страницы могут ссылаться на общие ресурсы. Простое удаление листов не обязательно удаляет все неиспользуемые объекты и не перекодирует изображения. Для полной записи применяют garbage collection и deflate или удобный ez_save(), а затем проверяют результат.

Можно ли заменить Sumatra PDF на PyMuPDF?

Только если задача — программная обработка, а не чтение человеком. PyMuPDF не даёт готового интерфейса просмотрщика. Для интерактивного просмотра Sumatra PDF гораздо ближе к нужному классу продукта, а PyMuPDF лучше воспринимать как движок автоматизации.

Вывод

PyMuPDF подходит разработчикам, аналитикам и инженерам, которым нужен один Python API для извлечения содержимого, рендеринга, геометрического анализа и изменения PDF. Особенно сильны сценарии, где координаты текста связываются с визуальной страницей: поиск и подсветка, маскирование данных, построение превью, извлечение таблиц, сборка документов и локальный OCR через Tesseract.

Выбирать PyMuPDF как обычный PDF-reader нерационально: у него нет собственного GUI, а порог входа определяется знанием Python и устройства PDF. Не лучший выбор он и для проекта, где AGPL несовместима с моделью распространения, а бюджет на коммерческую лицензию заранее не согласован. В таких случаях стоит рассмотреть pypdf или pikepdf в зависимости от функционального профиля и лицензии.


Ваш адрес email не будет опубликован. Обязательные поля помечены *