Skip to main content

frompdf

frompdf is a simple CLI tool for extracting structured text from PDFs.

The initial and primary output format is Markdown, with additional output formats planned. frompdf uses robust heuristics to detect paragraphs, headings at various levels, block quotes, and other document features. Running headers and footers are detected and removed, while page numbers can optionally be exported as metadata.

These heuristics can never be perfect, but they should often provide a useful approximation of the actual document content — one that is more useful than plain text extraction for RAG and similar workflows, or for turning read-only PDFs into editable structured text.

While ML-based alternatives such as Docling may handle some details better, they are slower and have considerably higher computational overhead. frompdf's heuristics will not get every detail right, but they are fast, robust, and easy to run locally.

frompdf is released under the permissive MIT License. This can make it easier to use, modify, and integrate than tools based on PyMuPDF, which is available under the GNU AGPL or a commercial license.

What frompdf does right now

The current version provides one command:

  • frompdf file.pdf - extract Markdown from a PDF

For an input named file.pdf, the command writes:

  • file.md - Markdown output

With diagnostic options, it can also write:

  • file-lines.csv - extracted line records with page, block, geometry, font size, and weight data
  • file-pagenos.csv - visible page numbers detected in headers or footers, if any are found

If file.md already exists, frompdf renames it to file.md.bak before writing the new output. Overwriting an existing .bak file is allowed.

Current Markdown Features

frompdf currently detects and serializes:

  • paragraphs
  • headings, based mostly on font size plus a document-relative font-weight boost
  • block quotes, based on indentation
  • repeated headers and footers, which are removed from the Markdown output
  • visible page numbers found in removed headers or footers

The internal block model tracks the raw PDF page number and, when available, the visible page number for each block.

Requirements

  • Python 3.11 or newer
  • pdftext, installed through this package's dependencies

Installation

For local use from a checkout of this repository:

pip install -e .

That installs the package in editable mode and makes the frompdf command available in the active Python environment.

If you prefer pipx for command-line tools, use editable mode when installing from a local checkout so the command sees local code changes:

pipx install -e .

Usage

Convert a PDF:

frompdf ./document.pdf

Example output:

document.md written

Write diagnostic CSV files as well:

frompdf --dump-lines --dump-pagenos ./document.pdf

Example output:

document-lines.csv written
document-pagenos.csv written
document.md written

--dump-lines writes the extracted line records. --dump-pagenos writes the page-number CSV only when visible page numbers were detected.

Limitations

PDFs do not contain document structure directly, so most higher-level structure has to be inferred. Current limitations include:

  • heading detection is heuristic and can miss headings or over-detect short emphasized text
  • block quote detection is conservative and currently relies on indentation
  • lists, tables, captions, footnotes, and code blocks are not modeled as dedicated block types yet
  • multi-column and heavily designed PDFs can still produce awkward reading order
  • header and footer removal depends on repetition and page-position heuristics

The diagnostic CSV files are part of the workflow: they make it easier to see why a specific line or block was classified the way it was.

Planned Direction

Planned next improvements include:

  • detection of lists, footnotes, and preformatted blocks
  • dehyphenation of words split across line breaks
  • better detection of paragraph boundaries, including merging paragraphs that span more than one page
  • correction of font-encoding and ligature-related text extraction errors
  • better support for multi-column PDFs
  • additional output formats such as HTML, EPUB, ODT, and DOCX

Development

See CONTRIBUTING.md for development setup, style rules, testing commands, and guidance for contributors and coding agents.

License

frompdf is distributed under the MIT license. See LICENSE.txt.

Metadata

Release files for frompdf 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for frompdf 0.1.0
File Size Uploaded Provenance Actions
frompdf-0.1.0.tar.gz 15.8 kB Without provenance Details for frompdf-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for frompdf 0.1.0
File Interpreter ABI Platform Actions
frompdf-0.1.0-py3-none-any.whl Python 3 none any Details for frompdf-0.1.0-py3-none-any.whl

Total release size: 29.2 kB

Release files / frompdf-0.1.0.tar.gz

Download URL frompdf-0.1.0.tar.gz
Size 15.8 kB
Tags Source
SHA-256 checksum
How to use checksums
5432904cfd7d29b76aa83570ca30216cad13deb9347962352325bd87a40fc185
BLAKE2b-256 checksum
How to use checksums
1bffcdba9db38b7ab98149141f80eee8ed8eea93847b84fba683ed7ab338917e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.3

Release files / frompdf-0.1.0-py3-none-any.whl

Download URL frompdf-0.1.0-py3-none-any.whl
Size 13.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f327c0c96e96b6c6d6317d3916213847433abc15589acec3bba412d38c3d00f2
BLAKE2b-256 checksum
How to use checksums
06fab450cf1d6f54e0eb62af901db776d160b05270da4c5766d1280ef2a288f7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.3

Security for frompdf 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page