Обзор pdfminer.six: извлечение текста, разметки и объектов PDF в Python

pdfminer.six — не просмотрщик и не редактор PDF, а библиотека и набор консольных инструментов для программного разбора документов. Её сильная сторона — извлечение текста вместе с координатами, параметрами шрифта и структурой страницы, а также доступ к внутренним объектам PDF. Такой профиль делает пакет полезным для разработчиков, аналитиков и исследователей, но почти бесполезным для пользователя, которому нужно просто открыть документ, поставить подпись или визуально исправить страницу. Актуальная стабильная версия на дату подготовки обзора — 20260107; она распространяется через PyPI, требует Python 3.10 или новее и относится к активно поддерживаемой ветке сообщества pdfminer.six.

Скачать pdfminer.six

Безопасный основной канал получения pdfminer.six — Python Package Index через pip. Официальная документация предлагает установку командой python -m pip install pdfminer.six или эквивалентным вызовом pip внутри выбранного окружения. На PyPI стабильным релизом указан 20260107, опубликованный 7 января 2026 года. Пакет также доступен как исходный архив и универсальный wheel с тегом py3-none-any, поэтому разработчики не распространяют отдельные установщики для Windows, macOS или Linux.

Для проектов с извлечением изображений официально предусмотрена дополнительная зависимость: python -m pip install «pdfminer.six[image]». Она добавляет Pillow. Если задача ограничивается текстом, структурой страниц и обычным парсингом, устанавливать этот extra заранее не требуется.

Исходный код ведётся в репозитории организации pdfminer на GitHub. Для рабочих систем лучше фиксировать стабильный релиз из PyPI: ветка разработки содержит пункты Unreleased, способные изменить поведение парсера.

Не следует путать имя дистрибутива и имя импортируемого модуля. Через pip устанавливается pdfminer.six, а в Python используются импорты вида from pdfminer.high_level import extract_text. Название сохраняет историческую связь с исходным PDFMiner, но современная ветка pdfminer.six является самостоятельным, поддерживаемым сообществом форком.

Что такое pdfminer.six

pdfminer.six — общественно поддерживаемая ветка оригинального PDFMiner, созданного Yusuke Shinyama. Первоначальная причина появления форка была практической: обеспечить работу архитектуры PDFMiner в Python 3. Суффикс six связан с одноимённой библиотекой совместимости Python 2 и Python 3, хотя поддержка Python 2 давно удалена. Название сохранили ради совместимости экосистемы и узнаваемости пакета.

В метаданных авторами указаны Yusuke Shinyama, Philippe Guglielmetti и Pieter Marsman. Проект позиционируется как community maintained, а не как продукт одного коммерческого вендора; репозиторий отдельно предупреждает об ограниченной доступности мейнтейнеров.

Назначение pdfminer.six — извлекать информацию из PDF и анализировать её программно. Библиотека читает внутреннее содержимое документа, строит иерархию объектов страницы, восстанавливает текстовые строки и блоки по геометрии символов, предоставляет координаты, шрифты, размеры и другие свойства. Это принципиально иной класс продукта, чем PDF-XChange Editor или другие настольные редакторы: pdfminer.six не показывает привычное окно с страницами и не предназначен для ручного редактирования документа.

Стабильная версия 20260107 добавила CMap типов 6, 10 и 12 и исправила ошибки парсинга. После неё в журнале уже есть пункты Unreleased, поэтому ветка разработки активна, а документация latest иногда может опережать опубликованный пакет.

Основные функции pdfminer.six

Извлечение текста и восстановление порядка чтения

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

Поведение анализа контролирует объект LAParams. Ключевые параметры задают допустимое перекрытие строк, расстояние между символами, порог вставки пробелов, расстояние между строками и влияние горизонтального или вертикального расположения блоков. Поэтому при сложной многоколоночной верстке можно не менять сам парсер, а адаптировать эвристику к конкретному типу документов.

Координаты, символы, шрифты и элементы страницы

Функция extract_pages возвращает страницы как иерархии layout-объектов. В них встречаются LTTextBox, LTTextLine, LTChar, LTFigure, LTLine, LTRect и LTImage. Для каждого символа можно получить позицию, размер и имя шрифта, а для геометрических элементов — координаты. Такая детализация полезна, когда нужно не просто получить сплошной текст, а понять, где именно на странице находились заголовки, подписи, колонки, линии или изображения.

Поддерживаются CJK-тексты и вертикальное письмо. Параметр detect_vertical включает соответствующий режим группировки строк.

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

Консольный инструмент pdf2txt.py умеет сохранять изображения из PDF в отдельный каталог при задании output-dir. Для расширенной работы с изображениями предусмотрена дополнительная зависимость Pillow. Это извлечение внедрённых графических ресурсов, а не рендеринг каждой страницы в картинку.

dumppdf.py предназначен для исследования внутренней структуры: выводит объекты документа, извлекает оглавление и встроенные файлы, выбирает объекты и показывает потоки в сыром, бинарном или текстовом виде.

Пароли, шифрование и формы

pdfminer.six поддерживает чтение документов, защищённых RC4 и AES, если передан корректный пароль. Пароль можно передать как параметр высокоуровневой функции или через опцию командной строки. Библиотека также умеет извлекать данные интерактивных форм AcroForm.

Оглавление, теги и низкоуровневый API

Через PDFDocument доступны Outlines и tagged content. Низкоуровневая цепочка PDFParser, PDFDocument, PDFResourceManager, PDFPageInterpreter и конвертеров позволяет заменять отдельные этапы собственными компонентами.

Форматы вывода

pdf2txt.py выводит text, HTML, XML и tag; extract_text_to_fp также принимает hOCR. Справочник API предупреждает, что надёжнее всего режим text, поэтому остальные представления нужно проверять на реальных документах.

Поддержки DOCX, XLSX или полноценного экспорта таблиц как таблиц нет. Если задача — получить строки и ячейки из отчётов, лучше использовать инструмент, который строит табличную модель поверх геометрии PDF; например, pdfplumber специально добавляет извлечение таблиц и визуальную отладку поверх pdfminer.six.

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

У pdfminer.six нет графического интерфейса. Рабочая среда состоит из терминала, Python-кода и документации API. Поэтому оценивать его «удобство» нужно не по панелям и кнопкам, а по тому, насколько быстро пользователь может перейти от PDF к программно проверяемому результату.

Командная строка

Для разовых задач проще всего pdf2txt.py. Он принимает один или несколько PDF, умеет ограничивать набор страниц, задавать пароль, поворот, параметры layout analysis, выходной файл, кодировку и каталог для извлечённых изображений. По умолчанию текст отправляется в стандартный вывод, что удобно для перенаправления в файл или конвейер командной строки. dumppdf.py ориентирован на диагностику и внутренние объекты документа, поэтому его набор параметров сложнее и менее дружелюбен для новичка.

Высокоуровневый Python API

Для большинства скриптов достаточно pdfminer.high_level: extract_text возвращает текст, extract_text_to_fp пишет его в поток, а extract_pages даёт структуру страницы. Этого хватает для индексации, поиска и извлечения полей.

Композиционный API и порог освоения

Низкоуровневая модель требует понимания объектов PDF, потоков, шрифтов и координат. Зато она позволяет вмешаться в конкретный этап разбора, когда стандартного extract_text недостаточно.

Документация и имена параметров англоязычные. Отдельного переключателя языка интерфейса нет, поскольку самого GUI нет. Русский текст в PDF обрабатывается как Unicode при наличии корректных отображений символов внутри документа; проблема языка здесь обычно связана не с локализацией библиотеки, а с качеством шрифтовых карт и текстового слоя исходного PDF.

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

Входной формат pdfminer.six — PDF. Проект заявляет поддержку почти всех возможностей спецификации PDF 1.7, но это не обещание полной совместимости с каждым документом: PDF допускает большое количество генераторов, расширений и нестрогих файлов. Библиотека умеет декодировать распространённые фильтры потоков, поддерживает Type1, TrueType, Type3 и CID-шрифты, CJK-карты, RC4 и AES.

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

В качестве выходных представлений доступны строка Python, текстовый поток, layout-объекты, HTML, XML, tag и hOCR, а изображения можно сохранять отдельно. Это не конвертер PDF в Word или Excel. Сохранение внешнего вида страницы также не является основной задачей: даже HTML-вывод строится на результатах анализа и имеет режимы normal, exact и loose, но его нужно рассматривать как вспомогательный формат, а не как замену PDF-рендереру.

Для сканированных документов без текстового слоя pdfminer.six не выполняет OCR. Если текст в просмотрщике нельзя выделить и скопировать, библиотеке часто просто нечего извлекать как Unicode. Для таких материалов сначала нужен этап распознавания; среди ориентированных на OCR решений на сайте есть отдельный обзор ABBYY FineReader.

Отдельной матрицы Windows/macOS/Linux нет: опубликован универсальный wheel, а совместимость определяется наличием Python 3.10+ и зависимостей на целевой системе.

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

Официальная документация не публикует универсальных чисел скорости или памяти. pdfminer.six выполняет разбор и layout analysis в процессе Python, поэтому расход ресурсов зависит от числа объектов, потоков, шрифтов и сложности конкретных страниц.

Для пакетной обработки важно ограничивать работу там, где полный разбор не нужен. В CLI есть maxpages и выбор конкретных страниц, а в API — maxpages и page_numbers. Отключение кэширования ресурсов тоже доступно, хотя это компромисс: оно меняет использование памяти и повторное обращение к ресурсам, поэтому применять параметр следует осознанно.

Журнал изменений показывает, что проект регулярно исправляет ошибки на повреждённых и пограничных PDF. В релизе 20251227 добавлен отказ от выполнения циклических ссылок на content streams; в 20260107 появилась проверка максимального размера начала xref и улучшена обработка ошибок при чтении потоков. Это не делает библиотеку невосприимчивой к некорректным файлам, но демонстрирует активную работу над устойчивостью парсера.

Есть важное различие между стабильным релизом и веткой разработки. В Unreleased после 20260107 перечислено изменение apply_png_predictor с переходом на bytearray для устранения конкретного сценария нехватки памяти и ускорения этой операции, а также исправление бесконечной рекурсии в повреждённых цепочках Prev. Пока эти пункты не выпущены отдельным стабильным релизом, нельзя приписывать их версии 20260107. Для систем, где встречаются такие проблемные файлы, следует отслеживать следующий релиз и тестировать его до обновления производства.

Для стабильности фиксируйте версию и храните корпус типовых и проблемных PDF. После обновления проверяйте не только отсутствие исключений, но и порядок блоков, Unicode и координаты ключевых элементов.

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

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

Версии имеют формат даты, например 20260107. Это удобно для понимания возраста релиза, но не отменяет обычной практики закрепления зависимости: новая дата может включать исправления, изменения поведения парсера или удаление поддержки старого Python. В декабре 2025 года проект последовательно выпустил несколько релизов, в том числе 20251230 с критически важным изменением безопасности.

В ноябре 2025 года для pdfminer.six было опубликовано предупреждение высокого уровня опасности о выполнении произвольного кода при обработке специально сформированного PDF из-за небезопасной загрузки pickle CMap. В официальном advisory версии ниже 20251230 обозначены как затронутые, а 20251230 и новее — как исправленные. Релиз 20251230 заменил хранение CMap из pickle на JSON. Поэтому устанавливать старые версии для обработки недоверенных файлов неразумно; актуальный 20260107 уже находится выше границы исправления.

MIT не создаёт лицензионной платы, но не отменяет расходов на тесты, обновления безопасности и поддержку собственного кода. Платного SLA у проекта нет.

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

Python и зависимости

Стабильная ветка требует Python 3.10 или новее. В метаданных перечислены Python 3.10, 3.11, 3.12, 3.13 и 3.14. Базовые зависимости — charset-normalizer версии 2.0.0 или новее и cryptography версии 36.0.0 или новее. Для extra image добавляется Pillow.

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

Отдельного перечня минимальных версий Windows, macOS или Linux проект не публикует. Пакет распространяется как универсальный Python wheel, поэтому основное условие — совместимый интерпретатор Python и возможность установить зависимости. Для серверов и контейнеров нужно отдельно учитывать платформенную доступность cryptography и Pillow, если используется расширенный набор функций.

Дисковое пространство и память

Официальных минимальных значений RAM или свободного места не задано. Размер установленного окружения зависит от Python и зависимостей, а потребление памяти во время обработки — от конкретного PDF. Для больших потоков и изображений лучше планировать лимиты на уровне приложения или контейнера и не считать отсутствие формальных требований обещанием фиксированного малого расхода ресурсов.

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

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

Преимущества и недостатки pdfminer.six

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

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

pdfplumber логично выбирать, когда нужен удобный слой над pdfminer.six для таблиц и геометрических примитивов. Он прямо построен на pdfminer.six и использует его параметры layout analysis, но добавляет более предметный API и визуальную диагностику извлечения таблиц. Для задач «найти таблицу, увидеть ячейки, проверить линии» это часто короче, чем собирать собственную модель из LT-объектов.

PyMuPDF охватывает рендеринг, извлечение и изменение документов. Он ближе к задачам, где вместе с текстом нужно получать изображение страницы или менять PDF; pdfminer.six специализируется на разборе текстовой структуры.

Sumatra PDF — Windows-просмотрщик многих документных форматов. Он нужен человеку для чтения и визуальной проверки; pdfminer.six получает данные программно. В одном процессе Sumatra PDF может служить контролем исходника, а pdfminer.six — автоматизировать извлечение.

Если вместо программного извлечения нужен настольный инструментарий для изменения страниц, форм и содержимого, разумнее смотреть в сторону Adobe Acrobat Pro или других редакторов. Для бесплатного Windows-набора с широким набором операций доступен отдельный обзор PDF24 Creator. Это другие продуктовые классы, и сравнивать их с pdfminer.six по числу «функций PDF» без учёта назначения некорректно.

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

Установка в изолированное окружение

1. Проверьте версию Python командой python —version. Для актуального pdfminer.six нужен Python 3.10 или новее.
2. Создайте отдельное окружение командой python -m venv .venv. Стандартный модуль venv создаёт изолированный набор пакетов, не смешивая зависимости проекта с системной установкой Python.
3. Активируйте окружение. В Windows PowerShell используется .\.venv\Scripts\Activate.ps1, в cmd — .venv\Scripts\activate.bat, в bash/zsh на POSIX — source .venv/bin/activate.
4. Установите пакет: python -m pip install pdfminer.six. Если нужны операции с изображениями, используйте python -m pip install «pdfminer.six[image]».
5. Проверьте импорт: запустите Python, выполните import pdfminer и выведите pdfminer.__version__. Версия должна совпасть с установленным релизом.
6. Проверьте CLI командой pdf2txt.py —version. Официальная инструкция использует этот способ как тест наличия консольного инструмента.

Первый запуск

Для минимальной проверки возьмите небольшой машинно-сгенерированный PDF, где текст можно выделить в просмотрщике. Выполните pdf2txt.py example.pdf. Если на экране появляется читаемый текст и процесс завершается без ошибки, базовая цепочка установки работает. Для проекта лучше затем повторить тест через Python-функцию extract_text, потому что именно программный интерфейс обычно будет использоваться в приложении.

Обновление без потери воспроизводимости

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

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

Если пакет установлен в отдельном venv, наиболее чистый способ выхода — удалить весь каталог виртуального окружения после сохранения списка зависимостей и исходного кода проекта. Сам venv по документации Python считается воспроизводимым и одноразовым. Если нужно удалить только пакет, pip поддерживает команду python -m pip uninstall pdfminer.six. После удаления проверьте, что другие компоненты проекта не требуют эту зависимость.

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

Извлечь текст из набора договоров для полнотекстового поиска

Цель: получить текст из машинно-сгенерированных PDF. Подготовка: взять короткий, длинный и многоколоночный образцы. Шаги: вызвать extract_text и сохранить UTF-8 результат вместе с идентификатором исходника. Проверка: найти известные фразы. Ограничение: сложная верстка требует настройки LAParams, а сканы — OCR.

Найти текст по координатам и размеру шрифта

Цель: отличить заголовки от основного текста или извлечь поле из фиксированной зоны формы. Подготовка: выбрать страницу с известной разметкой. Шаги: пройти по extract_pages, отфильтровать LTTextContainer и при необходимости спуститься до LTChar; использовать bounding box, fontname и size для правил. Проверка: вывести координаты нескольких известных заголовков и сверить их положение визуально. Ограничение: одинаковый визуальный стиль может быть закодирован разными шрифтами или размерами в разных генераторах PDF, поэтому правило лучше строить на нескольких признаках.

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

Цель: сохранить графику из PDF отдельно от текста. Подготовка: установить extra image, если он нужен для выбранных форматов. Шаги: вызвать pdf2txt.py с output-dir, указав отдельный каталог вывода. Проверка: проверить количество созданных файлов, открыть выборочные изображения и сопоставить их с исходными страницами. Ограничение: эта операция извлекает встроенные изображения и не заменяет рендеринг каждой страницы целиком; текст и векторные элементы страницы не превращаются автоматически в один растровый файл.

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

• Симптом: текст пустой, а страница визуально содержит буквы. Проверьте, выделяется ли текст в обычном просмотрщике. Если нет, вероятнее всего это скан или контуры; нужен OCR, а не настройка pdfminer.six.
• Симптом: в тексте появляются (cid:x). Это признак отсутствующей или неполной Unicode-карты. Скопируйте тот же фрагмент из просмотрщика: если и там получается мусор, библиотека не может восстановить символы из отсутствующей информации.
• Симптом: колонки перемешаны. Проверьте LAParams, особенно char_margin, word_margin, line_margin и boxes_flow. Меняйте один параметр за раз и сравнивайте с эталонной страницей.
• Симптом: ошибка на конкретном повреждённом PDF. Сначала подтвердите, что установлена актуальная стабильная версия, затем локализуйте страницу через page_numbers или maxpages. Для низкоуровневой диагностики используйте dumppdf на копии файла.
• Симптом: процесс съедает слишком много памяти. Ограничьте страницы, избегайте ненужного извлечения изображений и проверьте следующий стабильный релиз, если проблема связана с потоками PNG predictor: соответствующее улучшение уже отмечено в Unreleased после 20260107.
• Симптом: после установки импортируется неожиданная версия. Сравните путь интерпретатора, python -m pip и pdfminer.__version__. Причина часто находится в другом виртуальном окружении, а не в самом PDF.

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

• Зафиксируйте версию pdfminer.six, которой получен результат.
• Сохраните связь результата с исходным PDF: имя, хеш или внутренний идентификатор.
• Сверьте несколько страниц, включая многоколоночную и страницу с нестандартными шрифтами.
• Проверьте отсутствие (cid:x) и неожиданных пропусков Unicode.
• Если важна геометрия, проверьте координаты хотя бы одного известного элемента на каждой разновидности шаблона.
• Не считайте HTML/XML визуально точной копией PDF без отдельной верификации.
• Если обрабатывались персональные или коммерчески чувствительные документы, проверьте путь дальнейшего хранения текста и логов: сама локальная библиотека не отправляет результат в облачный сервис, но это может делать окружающее приложение.

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

pdfminer.six и PDFMiner — это одно и то же?

Это одна историческая линия, но не одна актуальная ветка. pdfminer.six возник как форк оригинального PDFMiner с поддержкой Python 3 и сегодня поддерживается отдельным сообществом. В официальном FAQ указано, что исходный PDFMiner с 2020 года неактивен, а pdfminer.six является рекомендуемой активной веткой.

Почему пакет устанавливается как pdfminer.six, а импортируется как pdfminer?

Имя дистрибутива в PyPI и Python namespace различаются. Установка выполняется для pdfminer.six, но модули находятся в пространстве pdfminer. Это нормальное устройство пакета, поэтому для диагностики версии полезно проверять именно pdfminer.__version__ в том интерпретаторе, которым запускается приложение.

Может ли pdfminer.six распознать скан?

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

Можно ли получить таблицу сразу как CSV или DataFrame?

Специализированного высокоуровневого табличного экстрактора в pdfminer.six нет. Можно анализировать координаты символов, линий и прямоугольников и построить собственную модель, но для готовой логики таблиц обычно удобнее pdfplumber, который работает поверх pdfminer.six и добавляет поиск таблиц и визуальную отладку.

Можно ли использовать pdfminer.six без записи PDF на диск?

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

Можно ли редактировать PDF и сохранить его обратно?

Это не профиль pdfminer.six. Библиотека предназначена для чтения, извлечения и анализа. Если нужен визуальный редактор, формы, перестановка страниц или сохранение изменённого документа, стоит выбрать соответствующий редактор; например, на сайте есть обзор Foxit Reader для пользовательской работы с PDF.

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

Используйте только актуальную версию. Уязвимость высокого уровня опасности в старых сборках была закрыта начиная с 20251230, а текущая стабильная 20260107 включает это исправление. Для входных файлов из недоверенных источников разумно дополнительно запускать обработку с минимальными привилегиями, лимитами CPU и памяти и без доступа к лишним секретам.

Вывод

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

Она не подходит как универсальная «программа для PDF» в пользовательском смысле. Здесь нет GUI, OCR, полноценного редактора, конвертации в DOCX/XLSX и готового табличного распознавания. Для сканов разумнее сначала использовать OCR, для таблиц — специализированный слой вроде pdfplumber, для рендеринга и изменения документов — инструмент класса PyMuPDF, а для ручного просмотра — Sumatra PDF или другой просмотрщик. Если нужен визуальный редактор с привычными командами, pdfminer.six следует исключить из списка кандидатов сразу, а не пытаться достроить поверх библиотеки интерфейс без необходимости.

Для старта разумен релиз 20260107 в отдельном окружении с закреплённой версией: он новее исправления безопасности 20251230 и поддерживает Python 3.10–3.14. В производстве важнее всего держать эталонный набор PDF и перепроверять текст и координаты после обновлений.