pdfcpu: возможности, ограничения и практическое применение PDF-инструмента командной строки

pdfcpu — не ещё один просмотрщик PDF, а открытый процессор документов для командной строки и Go-приложений. Он рассчитан на операции, которые удобно повторять и автоматизировать: проверку структуры PDF, оптимизацию, объединение и разбиение файлов, работу со страницами, шифрование, водяные знаки, формы, вложения и метаданные. На 14 сентября 2026 года актуальным стабильным выпуском является v0.15.0 от 11 августа 2026 года. Для обычного чтения документов pdfcpu неудобен, зато в сценариях пакетной обработки и серверной автоматизации его роль принципиально отличается от роли настольного PDF-ридера.

Скачать pdfcpu

Безопасный путь получения pdfcpu — официальная документация проекта и страница релизов репозитория pdfcpu/pdfcpu. Для v0.15.0 опубликованы архивы готовых бинарников и файл контрольных сумм. Документация CLI перечисляет сборки для macOS на Apple Silicon и Intel, Linux на x86_64, arm64, armv7 и i386, а также Windows на x86_64 и i386. После загрузки архив распаковывается, а целостность разумно сверить с опубликованным checksums.txt до помещения исполняемого файла в каталог из PATH.

Второй официальный способ — установка через Go: команда go install github.com/pdfcpu/pdfcpu/cmd/pdfcpu@latest собирает текущий CLI из модуля. В теге v0.15.0 файл go.mod объявляет версию языка Go 1.25.0. Этот вариант нужен разработчикам и тем, кто хочет воспроизводимую сборку; пользователю готового бинарника устанавливать Go не требуется.

Для macOS документация также указывает Homebrew и MacPorts, а для Fedora — пакет через DNF/YUM. Есть инструкция запуска в Docker. Это не разные коммерческие редакции: CLI и Go API относятся к одному открытому проекту и одной кодовой базе. Для проверки установки используется pdfcpu version, где выводятся версия, данные сборки и путь к конфигурации.

Что такое pdfcpu

pdfcpu — библиотека обработки PDF на Go и командная утилита поверх той же функциональности. Проект ориентируется на терминальные рабочие процессы, серверную автоматизацию и встраивание операций с PDF в Go-бэкенды без тяжёлого внешнего рантайма. Репозиторий находится в организации pdfcpu, а сопровождающим проекта указан Horst Rutter. Код распространяется по Apache License 2.0.

По позиционированию это процессор и инструмент преобразования структуры документов, а не средство визуального чтения. У pdfcpu нет окна с миниатюрами страниц, панели аннотаций или режима «открыть и читать». Пользователь задаёт команду, входные файлы, параметры и выходной путь; в Go-приложении те же задачи доступны через API. Большинство операций имеют файловую и потоковую форму, что удобно для серверов и конвейеров.

Проект активен. В 2026 году вышли v0.12.0, v0.12.1, v0.13.0, v0.14.0 и v0.15.0. Ветка 0.13 добавила более широкую поддержку stdin/stdout и более безопасную политику перезаписи, 0.14 усилила обработку ошибок, временных файлов и криптографических компонентов, а 0.15 улучшила диагностику пакетной валидации и обработку повреждённых структур. Официальное описание указывает поддержку PDF 1.7 и развивающуюся поддержку PDF 2.0; полноту PDF 2.0 нельзя считать завершённой.

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

Проверка, анализ и оптимизация PDF

Команда validate проверяет PDF и поддерживает relaxed и strict режимы. Relaxed является типичным режимом для реальных документов с допустимыми отклонениями популярных генераторов, strict требует более строгого соответствия реализованным правилам. Это именно проверка правил, реализованных pdfcpu, а не сертификат полного соответствия ISO 32000. Команда info выводит сведения о документе, а optimize переписывает PDF с оптимизацией ресурсов и удалением избыточности, которую способен определить движок.

Для больших наборов файлов v0.15.0 особенно полезна пакетная валидация по шаблону. Утилита может раскрывать рекурсивный шаблон вроде «**/*.pdf», немедленно сообщать об ошибке каждого проблемного файла и завершать проход сводкой. Флаг progress показывает активный файл даже при quiet-режиме. Это делает pdfcpu пригодным для технического аудита архива без написания внешнего цикла только ради перебора имён.

Сборка, разбиение и перестройка страниц

Набор document- и page-команд включает merge, split, trim, collect, pages insert/remove, rotate, crop, resize, zoom, nup, grid, booklet, poster, ndown и cut. Поэтому pdfcpu умеет не только склеить несколько документов, но и составить произвольную последовательность страниц, удалить выбранные страницы, повернуть их, изменить геометрию, разместить несколько страниц на одном листе или подготовить раскладку буклета.

Штампы, водяные знаки и параметры просмотра

pdfcpu различает stamp и watermark по положению относительно существующего содержимого страницы: stamp добавляется поверх, watermark — позади. В обоих случаях источником может быть текст, изображение или страница другого PDF. Настраиваются положение, масштаб, поворот, прозрачность и, для текста, шрифт и параметры рендеринга. Элементы можно добавлять, обновлять и удалять.

Отдельные команды управляют закладками, аннотациями, page mode, page layout и viewer preferences; закладки можно экспортировать и импортировать через JSON. Визуального редактора комментариев при этом нет.

Создание PDF и работа с формами

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

Раздел form позволяет перечислять поля, удалять их, блокировать и разблокировать, сбрасывать значения, экспортировать структуру в JSON, заполнять форму из JSON и выполнять массовое заполнение. Для multifill источником данных может быть JSON или CSV; по набору записей создаются отдельные экземпляры, а при нужном режиме результаты могут быть объединены.

Шифрование, пароли, разрешения и подписи

pdfcpu умеет шифровать и расшифровывать PDF, менять user password и owner password, а также читать и задавать разрешения. Owner password должен быть непустым, если пользователь хочет установить ограничения доступа.

Раздел доверия включает хранилище сертификатов и проверку цифровых подписей. В актуальном списке команд есть signatures validate и signatures remove. Команды создания цифровой подписи в текущем CLI нет, поэтому pdfcpu нельзя выдавать за полноценный инструмент подписания документов. Проверка цепочек сертификатов и данных отзыва развивается, а v0.14 и v0.15 отдельно усиливали обработку PKCS#7, временных меток и диагностических сообщений.

Ресурсы, изображения, вложения и метаданные

Утилита может извлекать изображения, шрифты, содержимое страниц, отдельные страницы и метаданные. Команда images позволяет перечислять и извлекать изображения, а также заменять конкретный ресурс по номеру объекта либо по странице и идентификатору. У замены есть существенное ограничение: базовая реализация рассчитана на случаи без soft mask или alpha channel и требует совпадения размеров исходного и нового изображения.

Вложения, PDF-портфели, keywords и properties можно перечислять и изменять командами, что удобно при автоматической подготовке пакетов документов.

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

Интерфейс pdfcpu — командная строка. Рабочая логика состоит из имени команды, подкоманды, флагов, входного файла и места вывода. Для справки используется pdfcpu [command] —help. Команды сгруппированы по предметным областям: документ, страницы, содержимое, ресурсы, формы, безопасность, доверие и конфигурация. В актуальных версиях есть генерация автодополнения для bash, zsh, fish и PowerShell.

Для пользователя, привыкшего к графическим PDF-редакторам, порог входа заметный. Нужно понимать пути к файлам, кавычки оболочки, правила выбора страниц и семантику параметров. Зато после освоения одна команда становится воспроизводимым рецептом: её можно сохранить в сценарии, CI-задаче или инструкции и повторить для тысячи файлов без ручных кликов.

Унифицированные флаги облегчают работу: verbose и very verbose управляют диагностикой, quiet подавляет обычный вывод, force явно разрешает перезапись, offline отключает исходящий HTTP-трафик для функций, способных обращаться к сети, conf выбирает каталог конфигурации, pages задаёт диапазоны страниц. Начиная с v0.13 многие PDF-позиции принимают дефис для stdin или stdout, но поддержка потоков зависит от конкретной команды.

Команды и документация используют английские имена. Для редкой ручной задачи графическая программа обычно проще.

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

Основной объект обработки — PDF. Проект заявляет поддержку версий PDF до 2.0, но прямо оговаривает, что покрытие PDF 2.0 развивается и валидация этой спецификации пока не полная. На практике это означает: обычные PDF 1.x и множество реальных документов обрабатываются широко, однако необычные конструкции PDF 2.0 и повреждённые файлы нужно проверять на конкретной задаче.

Дополнительные форматы зависят от операции. JSON используется для create, экспорта и импорта закладок, описания viewer preferences и данных форм. CSV поддерживается в массовом заполнении форм. При работе с пользовательскими шрифтами документация разрешает простые TrueType-файлы TTF и коллекции TTC; OTF на странице управления шрифтами прямо отмечен как неподдерживаемый формат пользовательского шрифта. Для N-up в официальных примерах используются JPG, PNG и TIF.

Импорт изображений и генераторы страниц не превращают pdfcpu в универсальный конвертер офисных форматов. Он не заявлен как средство прямого открытия DOCX, XLSX, PPTX, EPUB или DjVu. Если источник — документ Office, его сначала нужно получить в PDF подходящим приложением, а уже затем использовать pdfcpu для структурной обработки.

Go API предоставляет файловые функции и варианты на io.ReadSeeker/io.Writer, а многие CLI-команды работают со stdin/stdout. Поэтому pdfcpu удобно включать в серверные конвейеры без лишних промежуточных файлов там, где потоковый режим поддерживается.

OCR в pdfcpu нет. Утилита может извлекать имеющееся содержимое и работать с PDF-структурой, но распознавать текст на сканах как специализированная OCR-система она не предназначена. Также нет визуального редактирования текста абзацами, как в полнофункциональном PDF-редакторе.

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

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

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

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

Ограничения остаются. Сам проект просит сообщать случаи, когда файл открывается в Adobe Acrobat Reader или macOS Preview, но не обрабатывается pdfcpu: это признание того, что реальный PDF-ландшафт содержит отклонения и пограничные конструкции. Для критичных архивов полезно хранить оригинал, валидировать результат и тестировать новую версию на репрезентативной выборке до массовой замены.

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

pdfcpu распространяется по Apache License 2.0. Официальный проект не делит функциональность на бесплатный и платный тарифы, не требует регистрации, подписки, пробного периода или активации. CLI и библиотека доступны как открытый исходный код; выпуск v0.15.0 является обычным публичным релизом.

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

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

Windows

Официальная страница установки публикует готовые сборки Windows x86_64 и i386. После выпуска v0.14 сопровождающий проекта указал, что экспериментальная сборка для Windows 7 прекращена, а обычные официальные сборки Go ориентированы на Windows 10 или Windows Server 2016 и новее. Для актуального использования старые Windows 7/8 не следует считать поддерживаемой целью.

macOS

Для macOS публикуются бинарники arm64 и x86_64, то есть поддерживаются Apple Silicon и Intel. Официальная инструкция предлагает также Homebrew и MacPorts. Точный минимальный номер macOS на странице прямой установки не закреплён, поэтому при старой системе нужно проверять конкретный бинарник, а не приписывать проекту неподтверждённый порог версии ОС.

Linux

В матрице загрузок перечислены x86_64, arm64, armv7 и i386. Для Fedora указан пакет golang-github-pdfcpu через DNF. Дистрибутив, версия ядра и минимальный объём RAM как жёсткие требования в официальной CLI-инструкции не заданы; фактический расход памяти существенно зависит от структуры документа и операции.

Сборка и Go API

Если используется готовый бинарник, отдельный Go не нужен. Если pdfcpu устанавливается через go install или подключается как библиотека, тег v0.15.0 объявляет в go.mod версию Go 1.25.0. Для контейнерного сценария репозиторий содержит Dockerfile и официальная документация показывает пример локальной сборки образа.

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

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

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

Большинство изменяющих команд pdfcpu создают выходной PDF или могут переписать файл при явном выборе соответствующего режима. Это означает, что наиболее надёжный «откат» — не надежда на Undo, а сохранённый оригинал. Командная строка не ведёт пользовательскую историю действий, как графический редактор.

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

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

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

• Открытый исходный код и Apache 2.0 без платной функциональной границы.

• Общая функциональность для CLI и Go API.

• Сильная пакетная и серверная автоматизация, включая stdin/stdout у многих команд.

• Широкий набор операций со страницами, формами, защитой, маркировкой, вложениями и метаданными.

• Локальная обработка без обязательного аккаунта или облачной загрузки.

• Готовые бинарники Windows, macOS и Linux; активные релизы 2026 года.

Минусы

• Нет GUI, визуального выбора страниц и встроенного ридера.

• Нет OCR и полноценного визуального редактирования существующего текста.

• Поддержка PDF 2.0 развивается и не считается полной.

• Подписи можно проверять и удалять, но актуальный CLI не создаёт их.

• Сложные параметры маркировки, create и геометрии требуют изучения синтаксиса.

• Экзотические или повреждённые PDF иногда требуют отдельной диагностики.

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

Сравнивать pdfcpu лучше не по количеству кнопок, а по роли в рабочем процессе. Ниже четыре решения, которые пересекаются с ним только частично.

qpdf ближе всего к pdfcpu по инженерной модели: это CLI и C++-библиотека для структурных преобразований PDF, включая линеаризацию и шифрование. pdfcpu отличается Go API и своим набором высокоуровневых команд для форм, ресурсов, create и маркировки.

PDFsam Basic проще для человека, который раз в неделю объединяет или режет документы. У него есть графическая оболочка, он работает локально и бесплатен, но круг задач заметно уже. Если вместо командной строки нужен визуальный редактор Windows, логичнее смотреть также на PDF-XChange Editor или кроссплатформенный Master PDF Editor.

Sumatra PDF и pdfcpu скорее дополняют друг друга: первый удобен для просмотра, второй — для преобразования и автоматизации. Для другого настольного набора инструментов можно рассмотреть PDF24 Creator.

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

Установка готового бинарника

1. На официальной странице CLI Installation или в релизах pdfcpu/pdfcpu выберите архив для своей ОС и архитектуры.

2. Скачайте архив и checksums.txt, затем сверяйте контрольную сумму.

3. Распакуйте бинарник в отдельный каталог и запустите pdfcpu version по полному пути.

4. При необходимости поместите бинарник в PATH; официальная Unix-инструкция приводит /usr/local/bin как пример.

5. Проверьте установку на копии документа командой pdfcpu validate sample.pdf.

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

При наличии совместимого Go toolchain используйте go install github.com/pdfcpu/pdfcpu/cmd/pdfcpu@latest, затем pdfcpu version. Для сборки со встроенным снимком сертификатов EU Trusted Lists документация показывает build tag pdfcpu_eutl.

Параметры, которые важно настроить сразу

После первого запуска pdfcpu создаёт конфигурационный каталог пользователя. Его местоположение можно увидеть в pdfcpu version или pdfcpu config list. Перед серьёзной пакетной задачей стоит проверить validationMode, сетевой режим offline, лимиты потоков и изображений, а также необходимость пользовательских шрифтов и сертификатов.

На сервере заранее задайте политику конфигурации: постоянный каталог либо переопределённый/отключённый conf для stateless-задач. Если внешняя сеть запрещена, включите offline до производственного запуска.

Обновление и удаление

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

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

Аудит большого каталога PDF

Цель. Найти документы, которые не проходят relaxed-валидацию, не создавая отдельный цикл обхода дерева.

Подготовка. Зафиксируйте версию pdfcpu и работайте с копией или каталогом только для чтения. Перейдите в корень набора файлов.

Шаги. Запустите pdfcpu validate -q —progress «**/*.pdf». Кавычки нужны, чтобы рекурсивный шаблон раскрывал сам pdfcpu, а не оболочка. Для более строгого прохода добавьте mode strict. Если нужно сохранить диагностику, перенаправьте stderr средствами своей оболочки в журнал.

Проверка результата. Успешный проход должен завершиться кодом 0. При ошибках v0.15.0 выводит проблемные файлы по мере обнаружения и итоговую сводку. Один подозрительный документ повторно запускают без quiet и при необходимости с очень подробной диагностикой.

Ограничение. Ошибка validate показывает несоответствие правилам pdfcpu или проблему чтения, но не заменяет визуальную и бизнес-проверку содержимого.

Сборка отчёта из нескольких PDF и контроль результата

Цель. Объединить главы, затем оставить нужный диапазон и повернуть выбранные страницы.

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

Шаги. Сначала выполните pdfcpu merge report-all.pdf cover.pdf part1.pdf part2.pdf. Затем сформируйте требуемый диапазон командой trim с pages и создайте новый файл. Если отдельные страницы имеют неверную ориентацию, примените rotate к выбранным страницам уже в отдельный выход.

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

Ограничение. merge и последующие преобразования меняют структуру документа; если критичны закладки, формы или подписи, проверяйте именно эти элементы после каждого этапа.

Массовое заполнение формы из таблицы данных

Цель. Создать серию одинаковых форм с разными значениями.

Подготовка. Исходный PDF должен содержать поддерживаемые поля формы. Сначала экспортируйте структуру формы в JSON и используйте её как ориентир по именам полей. Подготовьте JSON или CSV с набором экземпляров.

Шаги. Запустите form multifill, указав PDF-шаблон, файл данных и выходной каталог. При необходимости выберите режим объединения, чтобы дополнительно получить общий PDF.

Проверка результата. Сверьте количество созданных файлов с количеством записей, затем выполните form list для выборочных экземпляров и откройте несколько файлов в ридере, чтобы проверить отображение значений.

Ограничение. pdfcpu работает с поддерживаемыми PDF-формами, а не с любым визуально похожим бланком. Скан без интерактивных полей сам по себе не станет формой и не будет распознан OCR.

Добавление служебной маркировки без облачной загрузки

Цель. Нанести на локальный PDF текст «DRAFT» или иной штамп на выбранные страницы.

Подготовка. Решите, должен элемент находиться над содержимым или под ним: для первого применяется stamp, для второго watermark. Для нестандартного Unicode-шрифта предварительно установите поддерживаемый TTF/TTC в pdfcpu.

Шаги. Используйте stamp add или watermark add с текстовым режимом и описанием положения, масштаба, поворота и прозрачности. Пишите результат в новый файл, особенно если документ подписан или юридически значим.

Проверка результата. Откройте PDF в независимом просмотрщике и визуально проверьте все выбранные страницы; затем выполните validate.

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

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

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

Нужен ли интернет для pdfcpu?

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

Нужно ли создавать аккаунт?

Нет. У официального CLI нет регистрации или активации. Это локальная программа с открытым исходным кодом.

Есть ли у pdfcpu графическая версия?

Официальный продукт ориентирован на CLI и Go API. Отдельного официального настольного GUI с тем же набором функций документация проекта не описывает.

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

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

Можно ли редактировать существующий текст как в Acrobat?

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

Умеет ли pdfcpu подписывать PDF цифровой подписью?

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

Можно ли использовать pdfcpu в коммерческом продукте?

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

Что сохраняется после удаления программы?

Если удалён только бинарник, созданные PDF, скрипты и пользовательские файлы остаются. Отдельно существует конфигурационный каталог pdfcpu с config.yml, сертификатами и установленными пользовательскими шрифтами. Перед очисткой каталога стоит решить, нужны ли эти данные для последующей установки.

Что делать, если файл открывается в ридере, но pdfcpu его отклоняет?

Сначала повторить проблему на актуальной версии, запустить validate для одного файла с подробным выводом и проверить relaxed/strict режим. Если сбой воспроизводится, полезно сравнить с Adobe Acrobat Reader или macOS Preview, а при отчёте разработчикам предоставить минимальный файл без конфиденциальных данных и точную команду.

Вывод

pdfcpu подходит разработчикам, системным инженерам и техническим пользователям, которым нужна локальная, повторяемая и автоматизируемая обработка PDF. Его сильная сторона — сочетание богатого CLI с Go API: один инструмент охватывает проверку, оптимизацию, страницы, формы, защиту, водяные знаки, вложения, метаданные и генерацию PDF по данным. Отсутствие аккаунта и обязательного облака упрощает приватные и серверные сценарии.

Для обычного чтения pdfcpu выбирать не стоит: здесь удобнее Sumatra PDF или другой ридер. Для визуального редактирования текста, OCR, ручной работы с объектами и создания цифровых подписей разумнее полноценный PDF-редактор. Для простых операций split/merge без командной строки практичнее PDFsam Basic или другой настольный набор инструментов.

Наиболее оправдан pdfcpu там, где одна и та же операция повторяется много раз и должна быть воспроизводимой: проверка архивов, серверная генерация, подготовка документов в CI, массовое заполнение форм, добавление маркировки, нормализация страниц и создание конвейеров через stdin/stdout. При таких задачах отсутствие GUI становится не недостатком, а частью его инженерной модели.