Skip to content
Back to search

pdf-craft

PDF craft can convert PDF files into various other formats. This project will focus on processing PDF files of scanned books.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday

Check it deeper on your machine

It has changed since its scan on 19 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/oomol-lab/pdf-craft with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/oomol-lab/pdf-craft'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/oomol-lab--pdf-craft/badge.svg)](/listings/oomol-lab--pdf-craft)

HTML

<a href="/listings/oomol-lab--pdf-craft"><img src="/api/listings/oomol-lab--pdf-craft/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

This example uses remote OCR to convert a PDF to Markdown. Prepare **Python 3.11–3.13, Poppler, and a working DeepSeek OCR-compatible service configuration**. See the [installation guide](docs/en/INSTALLATION.md) for Poppler setup.

> Just need to convert a file without setting up a development environment or OCR service? [Use PDF Craft Online](https://pdfcraft.ai/pdf-craft/) and upload your PDF in a browser.

1. Install

python -m pip install pdf-craft

2. Convert a PDF

Place `input.pdf` in the directory where you run your script. Replace the URL, API key, and model name with your service configuration:

from pdf_craft import DeepSeekOCRVendorConfig, PDFCraft, PDFOptions

craft = PDFCraft(
    pdf=PDFOptions(
        ocr=DeepSeekOCRVendorConfig(
            base_url="https://example.com/v1",
            api_key="your-api-key",
            model="deepseek-ocr",
        ),
    ),
)

craft.convert_pdf_to_markdown("input.pdf", "output.md")

Async applications use the same options through `AsyncPDFCraft`; callbacks may also be `async def` functions and run on the caller's event loop:

import asyncio
from pdf_craft import AsyncPDFCraft, DeepSeekOCRVendorConfig, PDFOptions

async def main():
    craft = AsyncPDFCraft(pdf=PDFOptions(ocr=DeepSeekOCRVendorConfig(
        base_url="https://example.com/v1",
        api_key="your-api-key",
        model="deepseek-ocr",
    )))
    await craft.convert_pdf_to_markdown("input.pdf", "output.md")

asyncio.run(main())

Do not call the synchronous `PDFCraft` facade from a running event loop; use `AsyncPDFCraft` and `await` its corresponding method instead.

`https://example.com/v1` is a placeholder, not a working endpoint. Use a compatible service that actually provides the OCR model. See [OCR configuration](docs/en/OCR_BACKENDS.md) for other models. If you do not have an OCR service yet, you can convert your files with [PDF Craft Online](https://pdfcraft.ai/pdf-craft/).

Open `output.md` after conversion. Documents containing images also produce asset files; keep those files with the Markdown when moving or sharing it.

3. Create an EPUB

Reuse the configured `craft` instance above and replace the last line with:

craft.convert_pdf_to_epub("input.pdf", "output.epub")

Open `output.epub` in an EPUB reader. For title, author, and rendering options, see [PDF conversion and translation](docs/en/PDF_TRANSLATION.md). For installation or runtime problems, see [troubleshooting](docs/en/TROUBLESHOOTING.md).

For EPUB bibliographic metadata, opt in to front-page OCR metadata extraction and provide a separate metadata LLM. PDF Craft accepts only values it can verify against OCR evidence. PDF file properties fill missing fields; they never override information printed in the book.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 241 lines
  1. <!-- Content baseline: docs/readmes/README-zh-CN.md. Preserve the Chinese README priorities in natural local copy; keep API examples accurate. -->
  2. <div align="center">
  3. <img src="docs/images/pdf-craft-readme-banner-v1.png" alt="PDF Craft — Bring scanned books back to editable, readable text." width="100%" />
  4. <p><strong>English</strong> | <a href="docs/readmes/README-zh-CN.md">简体中文</a> | <a href="docs/readmes/README-zh-TW.md">繁體中文</a> | <a href="docs/readmes/README-ja.md">日本語</a> | <a href="docs/readmes/README-ko.md">한국어</a> | <a href="docs/readmes/README-ru.md">Русский</a> | <a href="docs/readmes/README-fr.md">Français</a> | <a href="docs/readmes/README-es.md">Español</a> | <a href="docs/readmes/README-de.md">Deutsch</a> | <a href="docs/readmes/README-it.md">Italiano</a></p>
  5. <p>
  6. <a href="https://pypi.org/project/pdf-craft/"><img src="https://img.shields.io/pypi/v/pdf-craft.svg?color=AD493B" alt="PyPI" /></a>
  7. <a href="https://pypi.org/project/pdf-craft/"><img src="https://img.shields.io/pypi/pyversions/pdf-craft.svg" alt="Python" /></a>
  8. <a href="https://github.com/oomol-lab/pdf-craft/actions/workflows/merge-build.yml"><img src="https://img.shields.io/github/actions/workflow/status/oomol-lab/pdf-craft/merge-build.yml" alt="CI" /></a>
  9. <a href="LICENSE"><img src="https://img.shields.io/github/license/oomol-lab/pdf-craft" alt="MIT" /></a>
  10. </p>
  11. <p>
  12. <a href="https://trendshift.io/repositories/15538"><img src="https://trendshift.io/api/badge/repositories/15538" alt="PDF Craft | GitHub Trending on Trendshift" width="250" height="55" /></a>
  13. </p>
  14. <p>
  15. <a href="https://pdfcraft.ai/pdf-craft/"><strong>Convert PDFs online</strong></a> ·
  16. <a href="#quick-start"><strong>Python quick start</strong></a> ·
  17. <a href="#documentation"><strong>Documentation</strong></a>
  18. </p>
  19. </div>
  20. PDF Craft is a Python library for scanned books, research papers, and technical documents. It converts scanned PDFs into editable Markdown or reader-friendly EPUB. It can also translate PDF and EPUB content into another language, create translated or bilingual EPUBs, and write translations back onto the original PDF pages. It recognizes body text, chapters, tables of contents, footnotes, tables, formulas, and images so the content can be searched, edited, and read beyond the scanned page.
  21. ## Convert online — no installation needed
  22. Have a scanned PDF you want to edit or read as an ebook? Use **[PDF Craft Online · pdfcraft.ai](https://pdfcraft.ai/pdf-craft/)**: upload your file in a browser, submit a conversion task, and download the result when it is ready. There is no Python to install, no CUDA to configure, and no OCR provider or API key to set up.
  23. PDF Craft Online is the official online service for this open-source project. Use it to convert your files directly, or use the Python library below to build conversion into your own application or run OCR on your own machine.
  24. **[Upload your PDF and convert it online →](https://pdfcraft.ai/pdf-craft/)**
  25. [![PDF Craft Online conversion interface — click to upload a PDF](docs/images/website-en.png)](https://pdfcraft.ai/pdf-craft/)
  26. ## Conversion examples
  27. **Markdown: edit, search, and process the content.**
  28. ![PDF to Markdown example](docs/images/pdf2md-en.png)
  29. **EPUB: read the book in an ebook reader.**
  30. ![PDF to EPUB example](docs/images/pdf2epub-en.png)
  31. Results depend on scan quality, page layout, and the OCR model. Check a representative document before processing a larger collection.
  32. **Want to see how your own file turns out? [Upload a PDF and convert it to Markdown or EPUB →](https://pdfcraft.ai/pdf-craft/)**
  33. ## What you can do
  34. | Your goal | PDF Craft provides |
  35. | --- | --- |
  36. | Edit scanned books | PDF → Markdown, with text and image assets |
  37. | Read in an ebook reader | PDF → EPUB, with book metadata and table of contents |
  38. | Read books in another language | Translate during conversion or translate an existing EPUB; translation-only and bilingual output modes |
  39. | Create a translated PDF | Translate extracted text and write it back onto the source pages |
  40. | Integrate conversion into an app | Python APIs and reusable extraction files for later rendering or translation |
  41. ## Choose how to use it
  42. | Path | Best for | Requirements |
  43. | --- | --- | --- |
  44. | **[Online conversion](https://pdfcraft.ai/pdf-craft/)** | Upload a file and download Markdown or EPUB | A browser; no Python installation or OCR service setup |
  45. | **Python + remote OCR** | Developers who do not want to run OCR models locally | Python, Poppler, a compatible OCR service URL and credentials |
  46. | **Python + local OCR** | Developers with their own NVIDIA GPU | Python, Poppler, CUDA, sufficient VRAM, and model files |
  47. Remote OCR sends pages to the configured service and does not require local CUDA. Local OCR runs on your machine; using a remote LLM for translation or table-of-contents analysis still sends the corresponding content to that service.
  48. <a id="quick-start"></a>
  49. ## Python quick start
  50. This example uses remote OCR to convert a PDF to Markdown. Prepare **Python 3.11–3.13, Poppler, and a working DeepSeek OCR-compatible service configuration**. See the [installation guide](docs/en/INSTALLATION.md) for Poppler setup.
  51. > Just need to convert a file without setting up a development environment or OCR service? [Use PDF Craft Online](https://pdfcraft.ai/pdf-craft/) and upload your PDF in a browser.
  52. ### 1. Install
  53. ```bash
  54. python -m pip install pdf-craft
  55. ```
  56. ### 2. Convert a PDF
  57. Place `input.pdf` in the directory where you run your script. Replace the URL, API key, and model name with your service configuration:
  58. ```python
  59. from pdf_craft import DeepSeekOCRVendorConfig, PDFCraft, PDFOptions
  60. craft = PDFCraft(
  61. pdf=PDFOptions(
  62. ocr=DeepSeekOCRVendorConfig(
  63. base_url="https://example.com/v1",
  64. api_key="your-api-key",
  65. model="deepseek-ocr",
  66. ),
  67. ),
  68. )
  69. craft.convert_pdf_to_markdown("input.pdf", "output.md")
  70. ```
  71. Async applications use the same options through `AsyncPDFCraft`; callbacks may
  72. also be `async def` functions and run on the caller's event loop:
  73. ```python
  74. import asyncio
  75. from pdf_craft import AsyncPDFCraft, DeepSeekOCRVendorConfig, PDFOptions
  76. async def main():
  77. craft = AsyncPDFCraft(pdf=PDFOptions(ocr=DeepSeekOCRVendorConfig(
  78. base_url="https://example.com/v1",
  79. api_key="your-api-key",
  80. model="deepseek-ocr",
  81. )))
  82. await craft.convert_pdf_to_markdown("input.pdf", "output.md")
  83. asyncio.run(main())
  84. ```
  85. Do not call the synchronous `PDFCraft` facade from a running event loop; use
  86. `AsyncPDFCraft` and `await` its corresponding method instead.
  87. `https://example.com/v1` is a placeholder, not a working endpoint. Use a compatible service that actually provides the OCR model. See [OCR configuration](docs/en/OCR_BACKENDS.md) for other models. If you do not have an OCR service yet, you can convert your files with [PDF Craft Online](https://pdfcraft.ai/pdf-craft/).
  88. Open `output.md` after conversion. Documents containing images also produce asset files; keep those files with the Markdown when moving or sharing it.
  89. ### 3. Create an EPUB
  90. Reuse the configured `craft` instance above and replace the last line with:
  91. ```python
  92. craft.convert_pdf_to_epub("input.pdf", "output.epub")
  93. ```
  94. Open `output.epub` in an EPUB reader. For title, author, and rendering options, see [PDF conversion and translation](docs/en/PDF_TRANSLATION.md). For installation or runtime problems, see [troubleshooting](docs/en/TROUBLESHOOTING.md).
  95. For EPUB bibliographic metadata, opt in to front-page OCR metadata extraction and provide a separate metadata LLM. PDF Craft accepts only values it can verify against OCR evidence. PDF file properties fill missing fields; they never override information printed in the book.
  96. ## Optional input assertions
  97. Conversion does not automatically validate the whole input. If needed, call
  98. `assert_pdf_readable`, `assert_pdf_renderable`, `assert_pdf_editable`, or
  99. `assert_epub_readable` from `pdf_craft` before conversion. Choose the operation
  100. you need: success returns `None`, failure raises the original exception, and the
  101. input is never repaired or modified. Passing does not guarantee later OCR or
  102. translation succeeds. See [usage and capability limits](docs/en/ERROR_HANDLING.md#optional-input-assertions).
  103. ## Translation and reusable extraction
  104. **Translate books.** Supply an `XMLTranslator` when converting PDF to Markdown or EPUB, or translate an existing EPUB directly. Translation uses a separate text LLM; OCR and translation have independent configurations. EPUB translation can replace the original text or append the translation for bilingual reading.
  105. **Create a translated PDF.** Extract the content, translate it, and write the translation back onto the original pages. This workflow also needs Ghostscript and suitable local fonts. Check the resulting layout against the source and translated text.
  106. **Extract once, reuse later.** Save a `.pcex` extraction file for subsequent rendering, translation, or processing on another machine. Reuse the configured `craft` instance:
  107. ```python
  108. craft.convert_pdf_to_markdown(
  109. "input.pdf",
  110. "output.md",
  111. extraction_path="book.pcex",
  112. )
  113. ```
  114. **Preview content as it is processed.** PDF extraction, EPUB translation, and PCEX translation/rendering support optional callbacks. Receive source-mapped paragraphs, translated EPUB fragments, final PDF layout data, and finalized book metadata before the complete output file is ready. See [incremental callbacks](docs/en/STREAMING.md).
  115. See [PDF conversion and translation](docs/en/PDF_TRANSLATION.md), [EPUB translation](docs/en/EPUB_TRANSLATION.md), and the [`.pcex` format reference](docs/en/PCEX_FORMAT.md).
  116. ## OCR and runtime requirements
  117. PDF Craft supports **DeepSeek OCR, DeepSeek OCR 2, and Unlimited OCR**, each with local and remote configurations.
  118. The standard installation supports remote OCR. For local OCR, install the extra:
  119. ```bash
  120. python -m pip install "pdf-craft[local]"
  121. ```
  122. Local execution also requires a matching CUDA-enabled PyTorch build, sufficient VRAM, and model files. Models download from Hugging Face by default; you can also download them in advance and load them locally. Presets and requirements vary by model; see [OCR configuration](docs/en/OCR_BACKENDS.md).
  123. **Language support depends on the processing stage.** README languages describe documentation availability. Text recognition depends on the OCR model, and translation depends on the translator and text LLM. The EPUB `label_language` parameter selects fixed navigation/default-title labels (`zh` / `en`, with English as the default and fallback); it does not restrict content or translation languages; see the [API reference](docs/en/API_REFERENCE.md).
  124. <a id="documentation"></a>
  125. ## Documentation
  126. | Task | Guide |
  127. | --- | --- |
  128. | Preview task size and inspect remote resource consumption | [Usage and sizing](docs/en/USAGE.md) |
  129. | Install system dependencies and configure a local GPU | [Installation](docs/en/INSTALLATION.md) |
  130. | Select OCR models, remote services, or model caches | [OCR backends](docs/en/OCR_BACKENDS.md) |
  131. | Convert PDFs, create EPUBs, or write translations into PDFs | [PDF conversion and translation](docs/en/PDF_TRANSLATION.md) |
  132. | Translate existing EPUBs and configure bilingual output | [EPUB translation](docs/en/EPUB_TRANSLATION.md) |
  133. | Display incremental content and source locations | [Callback guide](docs/en/STREAMING.md) |
  134. | Understand extraction streaming and latency tradeoffs | [Design rationale (Chinese)](docs/design/pdf-extraction-streaming.md) |
  135. | Look up parameters, types, and methods | [API reference](docs/en/API_REFERENCE.md) |
  136. | Store or exchange extraction results | [`.pcex` format](docs/en/PCEX_FORMAT.md) |
  137. | Resolve installation and conversion issues | [Troubleshooting](docs/en/TROUBLESHOOTING.md) |
  138. | Upgrade to 2.6.0: retry and recovery policies | [Migration guide](docs/en/ERROR_HANDLING.md#upgrading-from-25x) |
  139. | Upgrade to 2.6.4: progress API migration and concurrency | [Release notes](docs/changelog/v2.6.4.md) · [Migration guide](docs/en/TRANSLATION_PROGRESS.md#breaking-migration) |
  140. ## Feedback and contributions
  141. Report problems or suggest improvements through [Issues](https://github.com/oomol-lab/pdf-craft/issues). For conversion problems, include the package version, OCR configuration type, error logs, and a minimal file you can share publicly. Remove credentials and private content first.
  142. [Pull requests](https://github.com/oomol-lab/pdf-craft/pulls) improving code, documentation, and translations are welcome. Use the Chinese README as the content baseline for all languages. Write naturally for local readers, preserving the focus on online conversion and translation capabilities, and keep API examples accurate.
  143. If PDF Craft helps you, a Star helps others discover it.
  144. ## Related projects
  145. [Wiki Graph](https://github.com/oomol-lab/wiki-graph) can turn converted EPUB or Markdown books into structured summaries, chapter topology, and knowledge graphs.
  146. ## License and acknowledgments
  147. PDF Craft uses the [MIT license](LICENSE). Third-party dependencies and selected OCR models retain their own licenses.
  148. Thanks to [DeepSeek OCR](https://github.com/deepseek-ai/DeepSeek-OCR), [DeepSeek OCR 2](https://github.com/deepseek-ai/DeepSeek-OCR-2), [Unlimited OCR](https://github.com/baidu/Unlimited-OCR), [doc-page-extractor](https://github.com/Moskize91/doc-page-extractor), [pyahocorasick](https://github.com/WojciechMula/pyahocorasick) and the open-source projects that make PDF Craft possible.
  149. <!-- community-footer:start -->
  150. ## Contributors
  151. Thanks to everyone who has contributed to PDF Craft. Contributions to code, documentation, and translations are welcome.
  152. [![PDF Craft contributors](https://contrib.rocks/image?repo=oomol-lab/pdf-craft)](https://github.com/oomol-lab/pdf-craft/graphs/contributors)
  153. ## Star History
  154. <!-- star-history:start -->
  155. <a href="https://www.star-history.com/#oomol-lab/pdf-craft&amp;Date">
  156. <picture>
  157. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=oomol-lab/pdf-craft&amp;type=Date&amp;theme=dark" />
  158. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=oomol-lab/pdf-craft&amp;type=Date" />
  159. <img alt="PDF Craft star history" src="https://api.star-history.com/svg?repos=oomol-lab/pdf-craft&amp;type=Date" />
  160. </picture>
  161. </a>
  162. <!-- star-history:end -->
  163. <!-- community-footer:end -->
  164. Translation progress reports source words (one Han character per word, long-word cap 20), with complete pre-scanned totals and per-round updates. See [translation progress](docs/en/TRANSLATION_PROGRESS.md).
  165. Extraction and translation share [unit progress events](docs/en/TRANSLATION_PROGRESS.md), with upfront counts, integer stages, and source words.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.