Содержание
  1. Что умеет PyMuPDF
  2. Документ и страницы
  3. Текст blocks words
  4. Полный учебный вход
  5. Порядок чтения
  6. Скан и OCR
  7. Когда нужен другой обработчик
  8. Частые вопросы
Обзоры

Обзор PyMuPDF: извлечение текста из PDF

16 ноября 2026 · 17 минут чтения

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

Что умеет PyMuPDF

Документация проекта на pymupdf.readthedocs.io описывает базовый набор операций над PDF: открытие файла, доступ к страницам, извлечение текста, поиск и извлечение таблиц, рендер страницы в изображение и запуск OCR. В разделе «The Basics» прямо сказано, что таблицы можно находить и извлекать с любой страницы документа. Это означает, что для типовых задач — вытащить текст, посмотреть структуру, отрисовать страницу — отдельный стек собирать не нужно.

Отдельно стоит разобраться с именами. В официальном туториале указано, что старые версии PyMuPDF использовали имя импорта fitz, а новые версии используют pymupdf и оставляют fitz как запасной вариант, чтобы старый код продолжал работать. Там же предупреждают: использование устаревшего имени fitz может сломаться, если в окружении установлен посторонний пакет fitz с pypi.org. Практический вывод простой: в новом коде пишите import pymupdf, а если видите import fitz в чужом примере — проверьте, что за пакет реально установлен.

Третий слой возможностей — работа с изображениями и рендером. Страницу можно отрисовать в картинку, а затем либо сохранить, либо подать на вход распознаванию. Это важно для документов, где текст присутствует как изображение. Документация в «The Basics» описывает такой случай отдельно: если документ содержит текст в виде изображения, для последующего извлечения текста применяют OCR на странице.

Что это даёт на практике:

  • открытие документа и доступ к страницам по индексу;
  • извлечение текста в разных форматах, включая plain text, blocks и words;
  • получение координат для блоков и слов;
  • рендер страницы в изображение;
  • поиск и извлечение таблиц;
  • запуск OCR для страниц с изображённым текстом.

Границы тоже видны из документации. В разделе рецептов по тексту сказано, что для PDF обычный вывод может идти не в привычном порядке чтения, содержать неожиданные переносы строк и так далее. PDF допускает порядок хранения, который отличается от визуального чтения. Проверяйте извлечение на своём макете. Поэтому дальше мы разберём, как получить текст по страницам, как работать с блоками и словами и как построить проверяемый порядок чтения для двухколоночной вёрстки.

Ещё один момент — установка. Пакет распространяется через pypi, и в экосистеме Python это стандартный путь: pip install pymupdf. Точные версии и зависимости смотрите в текущей документации проекта, потому что они меняются между релизами. Если вы переносите старый код, сначала проверьте имя импорта и наличие конфликтующего пакета fitz, а уже потом разбирайтесь с логикой извлечения.

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

Документ и страницы

Работа начинается с открытия документа. Документация проекта описывает число страниц через len(doc), что равно doc.page_count. Это первый ориентир: прежде чем извлекать текст, вы получаете размер документа и можете пройти по страницам циклом.

Доступ к странице идёт по индексу. В туториале отмечено, что отрицательные числа считаются с конца, поэтому doc[-1] — последняя страница, как и в обычных последовательностях Python. Это удобно для быстрых проверок: не нужно вычислять page_count - 1 вручную.

Документ можно использовать как контекстный менеджер. В туториале это указано явно: Document поддерживает работу через with. Такой стиль помогает не забыть закрыть файл и аккуратно освободить ресурсы, особенно когда вы обрабатываете много документов подряд.

Учебный пример. Возьмём документ из двух страниц, созданный в текстовом редакторе с разрывом страницы. Текст первой страницы:

ТЕКСТ4 строки
Клуб Орбита
Встреча: вторник, 18:00
Ответственный: Анна
Строка A-17: проверка входа

Текст второй страницы:

ТЕКСТ3 строки
Продолжение Орбиты
Материалы: список ссылок
Строка B-29: проверка выхода

Имена и коды здесь условные. Сохраните файл как fixture.pdf локально. Публичная ссылка на этот файл не предполагается, поэтому весь учебный вход задан текстом — вы воспроизводите его сами.

Задача библиотеки в этом примере: открыть документ, убедиться, что страниц две, извлечь текст отдельно для каждой страницы, не потерять маркеры A-17 и B-29 и не склеить страницы в один блок без разделителя. Последнее важно, потому что при пакетном извлечении страницы часто объединяют, и потом трудно понять, где закончилась одна и началась другая.

Для plain text в начале каждой страницы добавьте собственные маркеры «Страница 1» и «Страница 2». Так вы получите проверяемый ориентир: если маркер пропал, значит логика склейки или обрезки работает не так, как вы ожидали.

Порядок действий для этого шага:

  1. Откройте документ через контекстный менеджер.
  2. Получите число страниц через len(doc).
  3. Пройдите по страницам по индексу.
  4. Для каждой страницы извлеките текст отдельно.
  5. Сверьте наличие маркеров A-17 и B-29.
  6. Убедитесь, что страницы не слились в один блок без разделителя.

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

Ещё одна деталь — разделитель страниц. В примере рецепта авторы сами соединяют текст страниц через символ перевода страницы. Так рецепт организует вывод; произвольный вызов get_text() автоматически такой разделитель не добавляет. При собственном обходе страниц явно добавьте разделитель или сохраните каждую страницу отдельно.

Наконец, проверьте поведение на пустой странице. Если обычное извлечение вернуло пустую строку, в этом результате нет текста. Для заведомо растровой учебной страницы это ожидаемо. Для произвольного документа сначала осмотрите страницу и проверьте корректность обработки; одна пустая строка не устанавливает причину.

Текст blocks words

Формат вывода определяет, что вы получите на руки. В туториале описано, что режим "text" — это обычный текст с переносами строк, без форматирования, без сведений о позиции текста и без изображений. Это самый простой вариант, когда нужна только последовательность символов.

Для более тонкой работы есть blocks и words. В разделе рецептов по тексту указано, что каждый элемент списка содержит информацию о позиции своего текста, и эту информацию можно использовать для построения удобного порядка чтения. Отдельно сказано, что список отдельных слов извлекается через Page.get_text("words"), и его элементы — это слова с информацией о позиции.

Разница между форматами удобно свести в таблицу.

Формат Что возвращает Когда полезен
"text" Обычный текст с переносами строк Нужна только последовательность символов
"blocks" Блоки текста с позицией Нужно группировать текст по областям страницы
"words" Слова с координатами Нужен собственный порядок чтения
"dict" Структурированное представление Нужны вложенные детали по блокам и строкам

Режим "text" описан в туториале как вариант по умолчанию. Он даёт переносы строк, но не даёт позиций. Если документ одноколоночный и простой, этого достаточно. Если вёрстка сложная, позиции становятся необходимыми.

Блоки полезны, когда вы хотите работать с фрагментами страницы как с единицами. Например, заголовок, абзац и подпись к рисунку часто попадают в разные блоки. Получив блоки с координатами, вы можете фильтровать их по положению на странице.

Слова полезны, когда нужен максимально мелкий уровень. Из слов с координатами можно собрать строки, колонки и любой другой порядок. Это больше работы, но и контроль выше.

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

Ещё один формат — "dict". Он возвращает вложенную структуру с блоками, строками и текстовыми span. Отдельные слова с координатами получают через «words». Это удобно, когда нужно пройти по иерархии и обработать каждый уровень отдельно.

Что важно помнить при выборе формата:

  • "text" даёт минимум данных и минимум контроля;
  • "blocks" добавляет позиции на уровне блоков;
  • "words" даёт позиции на уровне слов;
  • "dict" даёт вложенную структуру.

Практический совет: начните с "text", посмотрите результат, и только если порядок или разбиение вас не устраивают, переходите к "blocks" и "words". Так вы не будете усложнять код без необходимости.

Отдельно про таблицы. В «The Basics» сказано, что таблицы можно находить и извлекать с любой страницы. Это отдельная возможность Page.find_tables(). Семантическая табличная разметка PDF для неё не является обязательным условием. Найденные строки, столбцы и значения нужно сверить с исходной страницей.

Полный учебный вход

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

Часть первая — две страницы с маркерами. Текст приведён в разделе про документ и страницы. Создайте PDF с разрывом страницы, сохраните локально.

Часть вторая — двухколоночная страница. Создайте вторую учебную версию PDF в текстовом редакторе: таблица из двух колонок без видимых границ. Левый столбец содержит две строки: «L1. Открой каталог» и «L2. Выбери книгу». Правый столбец: «R1. Подтверди выбор» и «R2. Сохрани номер заявки».

Ручной эталон читательского порядка для этого макета: L1, L2, R1, R2. Такой порядок задан для этого макета. На другом документе нужно отдельно определить расположение колонок и их последовательность.

Условные координаты PDF для этих строк:

ТЕКСТ4 строки
L1 = (40, 50, 240, 80)
L2 = (40, 100, 240, 130)
R1 = (300, 50, 500, 80)
R2 = (300, 100, 500, 130)

Условный алгоритм: сначала сгруппировать левую и правую колонку по x, затем отсортировать y внутри колонки. Результат: L1, L2, R1, R2. Простая сортировка по y, затем по x дала бы L1, R1, L2, R2. Это вручную вычисленная отрицательная проба; ответ PyMuPDF для этих координат не снимался.

Эти bbox заданы как полный бумажный вход. Они не измерены в сгенерированном PDF. Реальный вызов извлечения, рендера и OCR в рамках этого учебного входа не выполнялся.

Часть третья — контрольная проба со сканом. Экспортируйте первую страницу картинкой и вставьте её в новый PDF без текстового слоя. Пустой результат означает, что этот вызов не вернул текста; причину нужно установить по странице и параметрам обработки. Смысл документа при этом сохраняется: текст виден на изображении.

Что проверяет этот вход:

Часть Что проверяем Ожидаемый результат
Две страницы Разделение по страницам Маркеры A-17 и B-29 на месте
Две колонки Порядок чтения L1, L2, R1, R2 по эталону
Отрицательная проба Сортировка по y, затем x L1, R1, L2, R2
Скан без текстового слоя Наличие текстового слоя Пустой результат извлечения

Это авторский учебный вход. Реальный запуск внешнего сервиса, обучение модели, измерение скорости и платные API здесь не заявлены. Учебный результат сверяется с заданным входом, а параметры продукта — с текущей документацией.

Зачем такой полный вход. Он отделяет три разные проверки: разделение по страницам, порядок чтения и наличие текстового слоя. Если смешать их в одном тесте, непонятно, что именно сломалось. Раздельные проверки дают точный диагноз.

Порядок работы с этим входом:

  1. Создайте PDF с двумя страницами и маркерами.
  2. Создайте PDF с двумя колонками.
  3. Создайте PDF со сканом без текстового слоя.
  4. Прогоните извлечение по каждому файлу.
  5. Сверьте результат с эталоном для каждого файла.
  6. Зафиксируйте расхождения отдельно по каждой проверке.

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

Порядок чтения

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

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

Про параметр сортировки. В разделе рецептов указано, что сортировка выводит результат сверху слева вниз направо, и что для XHTML, HTML и XML выводов она игнорируется. Это полезно для простых страниц. Для сложной многоколоночной вёрстки одной сортировки недостаточно: она не знает, где заканчивается колонка и начинается следующая.

Разберём двухколоночный случай на учебном входе из предыдущего раздела. У нас есть четыре строки с условными координатами. Простая сортировка по y, затем по x даёт порядок L1, R1, L2, R2. Человек читает этот макет как L1, L2, R1, R2. Расхождение видно сразу.

Как построить правильный порядок. Нужно сгруппировать строки по колонкам, а затем отсортировать внутри каждой колонки. Группировка идёт по x: левая колонка имеет меньшие значения x, правая — большие. Внутри колонки сортировка идёт по y.

Условный алгоритм:

  1. Извлеките слова или блоки с координатами.
  2. Определите границу между колонками по значениям x.
  3. Разделите элементы на левую и правую группы.
  4. Отсортируйте каждую группу по y.
  5. Соедините группы в порядке слева направо.
  6. Сверьте результат с ручным эталоном.

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

Что важно проверить:

  • не перепутаны ли колонки местами;
  • не потерялись ли строки при группировке;
  • совпадает ли порядок с ручным эталоном;
  • воспроизводится ли результат при повторном запуске.

Отрицательная проба полезна тем, что показывает разницу между простой сортировкой и группировкой. Если ваш код даёт L1, R1, L2, R2, значит группировка не работает. Если даёт L1, L2, R1, R2, значит группировка сработала для этого макета.

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

Таблицы стоит проверять отдельным вызовом Page.find_tables(), затем сопоставлять найденные ячейки с макетом. Обычное извлечение текста само по себе не обещает восстановить табличные строки и столбцы.

Скан и OCR

Скан — это документ, где текст присутствует как изображение. В «The Basics» описан этот случай: если документ содержит текст в виде изображения, для последующего извлечения текста применяют OCR на странице. То есть распознавание запускается явно, отдельным шагом.

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

OCR запускается с собственными установленными зависимостями и проверкой языка. Это значит, что для распознавания нужно подготовить окружение: установить компоненты распознавания и указать язык. Без этого шага распознавание не заработает.

Порядок работы со сканом:

  1. Извлеките текст обычным способом.
  2. Если результат пустой, проверьте, есть ли на странице изображение.
  3. Отрендерите страницу в изображение при необходимости.
  4. Установите зависимости для OCR.
  5. Укажите язык распознавания.
  6. Получите OCR-TextPage через page.get_textpage_ocr() и передайте его в page.get_text(textpage=tp). Сам вызов OCR не меняет автоматически все последующие результаты извлечения.
  7. Сверьте результат с изображением вручную.

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

Что стоит помнить про качество. Распознавание зависит от качества скана: разрешение, контраст, наклон страницы влияют на результат. Чистый скан с ровным текстом распознаётся лучше, чем фотография под углом. Это свойство распознавания, и его нужно учитывать при планировании.

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

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

Наконец, про производительность. Распознавание — более тяжёлая операция, чем извлечение текстового слоя. Если документов много, стоит планировать время обработки и, возможно, распознавать только те страницы, где текстового слоя нет.

Когда нужен другой обработчик

PyMuPDF закрывает широкий круг задач, но есть случаи, где полезно посмотреть на другие инструменты. Разберём их по признакам.

Первый признак — сложная вёрстка с требованием точного порядка чтения. Если документ содержит несколько колонок, врезки, сноски и таблицы, построение порядка чтения становится отдельным проектом. Здесь помогает либо специализированный инструмент с готовыми эвристиками, либо ручная настройка под конкретный макет.

Второй признак — неудовлетворительное извлечение конкретной таблицы. Сначала проверьте Page.find_tables() и найденные ячейки. Если структура расходится с ручным эталоном, сравните другой обработчик на тех же входных файлах.

Третий признак — массовая обработка сканов. Если основной объём — изображения, стоит оценить отдельный конвейер распознавания с настройкой языка и предобработкой изображений.

Четвёртый признак — необходимость ручной визуальной правки документа. У PyMuPDF есть и операции изменения PDF; если пользователю нужен графический редактор, оцените отдельный интерфейс для этой работы.

Сравнение по признакам:

Признак PyMuPDF Другой обработчик
Простое извлечение текста Подходит Избыточен
Двухколоночная вёрстка Нужна своя логика порядка Готовые эвристики
Таблицы Page.find_tables() и сверка ячеек Сравнение на том же наборе PDF
Ошибки распознавания таблицы Настройка и ручной эталон Другой алгоритм для проблемных макетов
Сканы OCR отдельным шагом Конвейер распознавания
Визуальная правка Программные операции Графический PDF-редактор

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

Что не стоит делать. Не переписывайте весь конвейер из-за одного сложного документа. Сначала изолируйте проблему на минимальном примере, как в учебном входе. Часто достаточно добавить один шаг обработки.

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

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

Частые вопросы

Что такое PyMuPDF простыми словами?

Это библиотека Python для работы с PDF и другими документами. Она открывает файл, даёт доступ к страницам, извлекает текст в разных форматах, возвращает координаты блоков и слов, умеет рендерить страницу в изображение и запускать OCR. Базовый цикл описан в документации проекта на pymupdf.readthedocs.io.

Почему в примерах встречается import fitz?

Старые версии PyMuPDF использовали имя импорта fitz. Новые версии используют pymupdf и оставляют fitz как запасной вариант для совместимости. В официальном туториале предупреждают, что устаревшее имя может сломаться, если в окружении установлен посторонний пакет fitz с pypi.org. В новом коде пишите import pymupdf.

Как извлечь текст из двухколоночного PDF?

Извлеките блоки или слова с координатами. Затем сгруппируйте элементы по колонкам на основе значений x и отсортируйте внутри каждой колонки по y. Простая сортировка по y, затем по x даёт порядок L1, R1, L2, R2 на учебном макете, тогда как ручной эталон — L1, L2, R1, R2. Порядок задаёте вы, библиотека даёт координаты.

Что делать, если текст не извлекается?

Пустой результат показывает, что вызов не вернул текст. Осмотрите страницу: текст может быть частью изображения, но причина требует проверки. В этом случае отрендерите страницу и запустите OCR с установленными зависимостями и указанием языка. Документация проекта описывает этот случай в разделе «The Basics».

Можно ли извлечь таблицы?

Да, в документации проекта сказано, что таблицы можно находить и извлекать с любой страницы. Используйте Page.find_tables() и сопоставьте найденные ячейки с исходной страницей. Отдельная семантическая разметка таблицы не является обязательным условием; качество проверяют на конкретном макете.

Читайте также

3 материала