> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# pdftotext

> Extract the text of PDF files with poppler's pdftotext command line.

Write the text of a PDF file on any mount to standard output or to a text
file. Mirage implements [poppler](https://poppler.freedesktop.org)'s
`pdftotext` command line, layout, messages and exit codes with its own PDF
reader.

## Setup

`pdftotext` has no account config. It reads PDF files and writes text files
through existing mounts.

```python theme={null}
from mirage import MountMode, Workspace
from mirage.commands.cli.builtin.pdf import PDFTOTEXT
from mirage.vfs.ram import RAMVFS

ws = Workspace({"/data/": RAMVFS()}, mode=MountMode.WRITE)
ws.register_cli("pdftotext", PDFTOTEXT)
```

For YAML registration, see the [CLI overview](https://docs.mirage.strukto.ai/python/cli/index.md#register-a-cli).

## SKILL.md

The [SKILL.md](https://docs.mirage.strukto.ai/home/setup/cli/skill-md.md) an agent reads with `pdftotext` installed.

> [tab] Rendered
>
> **Available commands**
>
> These commands are registered with this shell; `--help` after a command or subcommand shows its usage.
>
> **`pdftotext`**
>
> ```text theme={null}
> usage: pdftotext [-f int] [-l int] [-layout] [-raw] [-nodiag] [-enc string] [-eol string] [-nopgbrk] [-opw string] [-upw string] [-q] [-h] [PDF-file [text-file] ...]
>
> Write the text of a PDF file to a text file, or to standard output when the text file is '-'. Pages end in a form feed.
>
> positional arguments:
>   PDF-file [text-file]  The PDF file, '-' for standard input; then the text file
>
> options:
>   -f int                 First page to read (default: 1)
>   -l int                 Last page to read (default: the last)
>   -layout                Keep each page's columns and spacing
>   -raw                   Keep text in the order the page draws it
>   -nodiag                Leave out text set at a slant
>   -enc string            Encoding of the text written; UTF-8 is the one served
>   -eol string            Line ending to write: unix, dos or mac
>   -nopgbrk               Write no form feed after each page
>   -opw string            Owner password of an encrypted file
>   -upw string            User password of an encrypted file
>   -q                     Print no messages and no errors
>   -h, -help, --help, -?  Show this help and exit
> ```

> [tab] Raw
>
> ````markdown theme={null}
> ---
> name: workspace-commands
> description: The CLIs registered in this workspace and how to call them.
> ---
>
> # Available commands
>
> These commands are registered with this shell; `--help` after a command or subcommand shows its usage.
>
> ## `pdftotext`
>
> ```text
> usage: pdftotext [-f int] [-l int] [-layout] [-raw] [-nodiag] [-enc string] [-eol string] [-nopgbrk] [-opw string] [-upw string] [-q] [-h] [PDF-file [text-file] ...]
>
> Write the text of a PDF file to a text file, or to standard output when the text file is '-'. Pages end in a form feed.
>
> positional arguments:
>   PDF-file [text-file]  The PDF file, '-' for standard input; then the text file
>
> options:
>   -f int                 First page to read (default: 1)
>   -l int                 Last page to read (default: the last)
>   -layout                Keep each page's columns and spacing
>   -raw                   Keep text in the order the page draws it
>   -nodiag                Leave out text set at a slant
>   -enc string            Encoding of the text written; UTF-8 is the one served
>   -eol string            Line ending to write: unix, dos or mac
>   -nopgbrk               Write no form feed after each page
>   -opw string            Owner password of an encrypted file
>   -upw string            User password of an encrypted file
>   -q                     Print no messages and no errors
>   -h, -help, --help, -?  Show this help and exit
> ```
> ````

## Supported commands

Run `pdftotext --help` for the supported flags and operands.
This list is generated from Mirage's registered command tree.

| Command | Description |
| - | - |
| `pdftotext` | Write the text of a PDF file to a text file, or to standard output when the text file is '-'. Pages end in a form feed |

## Usage

```bash theme={null} theme={null} theme={null}
pdftotext /data/report.pdf -
pdftotext -f 2 -l 4 /data/report.pdf - | grep -i revenue
pdftotext -layout /data/table.pdf -
pdftotext /data/report.pdf
cat /data/report.txt
```

`-` as the text file writes to standard output; with no text file, the text
goes beside the PDF with `.pdf` replaced by `.txt`. A PDF file of `-` is read
from standard input and then needs a text file. Each page ends in a form feed
unless `-nopgbrk` is given. By default text comes in reading order, one blank
line after each block; `-layout` keeps each page's rows and columns and `-raw`
keeps the order the page draws its text.

| Option | Effect |
| - | - |
| `-f N`, `-l N` | First and last page; out-of-range values are clamped as poppler clamps them |
| `-layout` | Keep columns and spacing |
| `-raw` | Keep drawing order |
| `-nopgbrk` | No form feed after each page |
| `-nodiag` | Leave out text set at a slant |
| `-eol unix\|dos\|mac` | Line endings |
| `-enc UTF-8` | Output encoding; UTF-8 is the one served |
| `-opw`, `-upw` | Owner or user password of an encrypted file |
| `-q` | No messages or errors; the exit code still reports them |

Encrypted files are read as poppler reads them; one that needs a password
opens with `-upw` or `-opw`. Pages without a text layer, such as scans, give empty text: there is no
OCR.

## Behavior

### Differences from poppler

* Text comes from Mirage's PDF reader, not poppler's. Where poppler prints raw
  glyph codes for a font with no usable encoding, the text may come out
  readable here.
* `-layout` keeps poppler's rows, but column widths can differ.
* Reading order can differ for cells set side by side in rows.
* `-r`, `-x`, `-y`, `-W`, `-H`, `-fixed`, `-htmlmeta`, `-tsv`, `-bbox`,
  `-bbox-layout`, `-cropbox`, `-colspacing`, `-listenc` and `-v` are not
  supported, and `-enc` takes only UTF-8. An option Mirage does not know is
  refused rather than read as a file name.
* Help is Mirage's own, and poppler's `Syntax Warning` lines about damaged
  content it reads anyway are not printed.

## License

| Project | Role in Mirage | License |
| - | - | - |
| [poppler](https://poppler.freedesktop.org) | Command-line behavior reference; Mirage copies none of its code | GPL |
| [pdf\_oxide](https://github.com/yfedoseev/pdf_oxide) | PDF reader dependency | MIT or Apache-2.0 |
| [Mirage](https://github.com/strukto-ai/mirage) | Command implementation | [Apache-2.0](https://github.com/strukto-ai/mirage/blob/main/LICENSE) |

See [compatibility and licenses](https://docs.mirage.strukto.ai/home/setup/clis.md#compatibility-and-licenses).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.