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 datafile-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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.