# Poppler utilities

PDF library whose command-line utilities (pdftotext, pdfinfo and others) extract text and metadata from PDF files.

## What is known from testing

On 2026-10-11, the headlesson operator ran all 7 steps of this lesson with Poppler utilities 26.04.0 (macOS26.5.2 arm64; Homebrew poppler 26.04.0 already installed (not reinstalled; upstream current is 26.10.0); test PDF made with macOS cupsfilter from self-made text), and all passed. The final Next step is advice and was not run. No independent check has been reviewed. This is the operator's own run, not a vendor claim.

- Test record: [test:wgxi8q](/tests/wgxi8q) — 2026-10-11, 26.04.0, passed

## Independent check

Independent check: not yet reviewed. (Whether an independent check exists has not been looked up for this record.)

## Description

Poppler is a PDF rendering library based on the xpdf-3.0 code base. Its utilities run locally and non-interactively; pdftotext writes the text layer of a PDF to a file or standard output, and pdfinfo prints document metadata such as page count, page size and encryption. pdftotext reads only text already in the PDF; it does not OCR scanned pages.

## Current lesson

Goal: Make a one-page PDF, read its metadata with pdfinfo and extract its text with pdftotext.

This is the current lesson. The test record above was run on the lesson as it was at its own revision; they can differ.

- 1. command -v pdftotext || brew install poppler
- 2. pdftotext -v
- 3. printf 'Invoice 2026-001\nTotal: 42 apples\n' > note.txt
- 4. cupsfilter -m application/pdf note.txt > note.pdf
- 5. pdfinfo note.pdf
- 6. pdftotext -layout note.pdf out.txt
- 7. grep -c 'Total: 42 apples' out.txt

Next (advice, not tested): Next: Agree with the user on the real PDF and the output path; run pdfinfo first to check page count and encryption, extract with pdftotext (add -f/-l for a page range), and if the text is empty or only form feeds, treat the PDF as scanned and switch to OCR.

## Cautions recorded with the lesson

These notes come from the lesson. Some describe failures seen in tests; others are general cautions. Each one is not a separately tested result.

- A PDF made only of page images gives no text; in the test pdftotext exited 0 and the output was a single form feed character. Check for empty output instead of relying on the exit code.
- pdftotext ends each page with a form feed (\f) page break; pass -nopgbrk to omit page breaks.
- Without a text-file argument pdftotext writes file.txt next to file.pdf; pass - to write to standard output.
- Exit codes per the installed man page: 0 no error, 1 error opening the PDF, 2 error opening the output file, 3 PDF permission error, 99 other error; a missing input exited 1 in the test.
- Default output follows reading order and undoes the physical layout; -layout keeps columns, and -tsv prints words with bounding boxes as tab-separated values.
- Step 3 uses the macOS cupsfilter command only to make a test PDF; on other systems use any small PDF that contains real text.
- Confirm: Check which PDF is read and where the text file is written (an existing output file is replaced), and confirm the extracted text is not empty before passing it to a downstream step.

## How to start

- cli pdftotext: install `brew install poppler`; check `pdftotext -v`; auth: None for local files.; docs: [https://poppler.freedesktop.org/](https://poppler.freedesktop.org/)

Where each of these values comes from is listed per field under Sources (/interfaces/N/field).

## Compared facts

- license: GPL-2.0-only OR GPL-3.0-only (checked 2026-10-11, secondary, third-party; source: [https://formulae.brew.sh/formula/poppler](https://formulae.brew.sh/formula/poppler))
- open_source: true (checked 2026-10-11, secondary, third-party; source: [https://formulae.brew.sh/formula/poppler](https://formulae.brew.sh/formula/poppler))
- pricing: free (checked 2026-10-11, inferred, editorial; source: [https://formulae.brew.sh/formula/poppler](https://formulae.brew.sh/formula/poppler))
- has_human_gui: none (checked 2026-10-11, inferred, editorial; source: headlesson editorial judgement)
- non_interactive: true (checked 2026-10-11, primary, editorial; source: headlesson editorial judgement)
- machine_output: true (checked 2026-10-11, primary, editorial; source: headlesson editorial judgement)
- local_mcp: unknown (not confirmed)
- remote_mcp: unknown (not confirmed)
- cli: true (checked 2026-10-11, primary, editorial; source: headlesson editorial judgement)
- rest_api: unknown (not confirmed)
- auth: none (checked 2026-10-11, inferred, editorial; source: headlesson editorial judgement)
- self_hostable: true (checked 2026-10-11, primary, editorial; source: headlesson editorial judgement)
- embeds_llm: unknown (not confirmed)
- refusal_contract: unknown (not confirmed)
- audit_log: unknown (not confirmed)
- last_release: 2026-10-04 (checked 2026-10-11, primary, official; source: [https://poppler.freedesktop.org/](https://poppler.freedesktop.org/))
- ja_support: unknown (not confirmed)

## Sources

Each line names fields of this page (as JSON pointers into the .json version) and where they come from. Labels without a link are non-public sources. Fields not listed (such as test results) are the headlesson operator's own observations.

- /name, /axes/last_release: [https://poppler.freedesktop.org/](https://poppler.freedesktop.org/) (checked 2026-10-11, primary, official)
- /one_liner, /lesson/goal, /lesson/next_advice, /lesson/cautions/items/5, /lesson/cautions/items/6, /interfaces/0/auth, /axes/has_human_gui, /axes/auth, /relations/0: headlesson editorial judgement (checked 2026-10-11, inferred, editorial)
- /description: [https://poppler.freedesktop.org/](https://poppler.freedesktop.org/) (checked 2026-10-11, primary, editorial)
- /lesson/steps/0, /interfaces/0/kind, /interfaces/0/name, /interfaces/0/install, /interfaces/0/docs: [https://formulae.brew.sh/formula/poppler](https://formulae.brew.sh/formula/poppler) (checked 2026-10-11, primary, third-party)
- /lesson/steps/1, /lesson/steps/2, /lesson/steps/3, /lesson/steps/4, /lesson/steps/5, /lesson/steps/6, /lesson/cautions/items/0, /lesson/cautions/items/1, /lesson/cautions/items/2, /lesson/cautions/items/3, /lesson/cautions/items/4, /interfaces/0/verify, /axes/non_interactive, /axes/machine_output, /axes/cli, /axes/self_hostable: headlesson editorial judgement (checked 2026-10-11, primary, editorial)
- /axes/license, /axes/open_source: [https://formulae.brew.sh/formula/poppler](https://formulae.brew.sh/formula/poppler) (checked 2026-10-11, secondary, third-party)
- /axes/pricing: [https://formulae.brew.sh/formula/poppler](https://formulae.brew.sh/formula/poppler) (checked 2026-10-11, inferred, editorial)

## Primary record

Test results here are the operator's own past lesson trials (legacy). They are not claimed to meet level L1 of run-task-contract/0.1.0.

## Relations

- used-for: [usecase:parse-documents-for-llm](/usecases/parse-documents-for-llm)

## Retrieve over MCP

`headlesson_get id="app:poppler" sections ["lesson","gotchas"]` on https://mcp.headlesson.com/mcp

## Cite

headlesson app:poppler: see test record test:wgxi8q (https://headlesson.com/tests/wgxi8q).

Page updated: 2026-10-13 (the date its content last changed).

要約（日本語）: Poppler utilities。運営の試用（2026-10-11、26.04.0、passed）の記録がある。詳しい条件・限界・出典は本文のとおり。