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

# Overview

> Install SoPDF, process a PDF in Python, and look up functions, objects, and exceptions.

## What is SoPDF

**SoPDF** is an open-source Python PDF processing library that covers the full workflow from rendering and text extraction to structural editing. You can use it to build production-grade parsing, retrieval, split/merge, and batch processing pipelines.

See the [API Docs](https://docs.somark.ai/en/open-source-tools/sopdf/examples.md) for functions, objects, and examples.

> [!NOTE]
>
> SoPDF is released under Apache 2.0. You can use it in personal projects, commercial products, and open-source libraries.

## Quick start

In an empty directory, install SoPDF with Python 3.10 or later and download a one-page test PDF. [W3C test PDF](https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf)

```bash theme={null}
python -m pip install sopdf
curl -fL https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf -o document.pdf
```

Save the code below as `quickstart.py` and run `python quickstart.py`. The first page is `doc[0]` because page indexes start at `0`.

```python theme={null}
from pathlib import Path

import sopdf

with sopdf.open("document.pdf") as doc:
    page = doc[0]
    Path("page-1.png").write_bytes(page.render(dpi=150))
    text = page.get_text().strip()
    Path("page-1.txt").write_text(text, encoding="utf-8")
    print(text)
```

The script writes a rendered image to `page-1.png`, saves the text to `page-1.txt`, and prints `Dummy PDF file`.

## Why SoPDF

* High performance: official benchmarks show major speedups vs PyMuPDF in core scenarios (up to about `2.82x` in rendering, `2.74x` in plain text extraction, and `3.17x` in full-text search).
* Feature complete: supports rendering, extraction, search, split/merge, compressed save, metadata, and outline handling.
* Clean API: designed for practical day-to-day engineering workflows.
* Permissive license: Apache 2.0 simplifies internal adoption and external distribution.

## Core capabilities

| Capability | Description |
| - | - |
| Open documents | Open PDFs from file paths, bytes, or streams |
| Page rendering | Render to PNG/JPEG, including batch and parallel rendering |
| Text workflows | Extract plain text, extract text blocks with bounding boxes, and search keywords |
| Document editing | Split, merge, rotate pages, and save with compression |
| Operational readiness | Handle encrypted PDFs and auto-repair corrupted PDFs |
| Document metadata | Read/write metadata and read document outline (TOC) |

## Architecture

SoPDF uses a dual-engine architecture:

* `pypdfium2` (Google PDFium): rendering, text extraction, and search.
* `pikepdf` (libqpdf): structure reads, writes, and save/compression.

With a dirty-flag + hot-reload sync mechanism, write operations are automatically reflected in the read path, so you do not need to manually coordinate both engines.

## Resources

* Repository: [SoMarkAI/SoPDF](https://github.com/SoMarkAI/SoPDF)
* PyPI: [sopdf](https://pypi.org/project/sopdf/)
* Examples: `examples/` in the repository
* Benchmark suite: `tests/benchmark/` in the repository

## License

[Apache License 2.0](https://github.com/SoMarkAI/SoPDF/blob/main/LICENSE)


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