PaddleOCR
github.com/paddlepaddle/paddleocr- Category
- AI Tools
- Rank
- No. 19Tools index
- Pricing
- Open Source
- Type
- TOOL
- Builder
- paddlepaddle
- GitHub
- 89.1k stars
- Latest release
- v3.7.0
- Date
About
An open-source OCR toolkit that converts PDF documents and images into structured, LLM-ready data (JSON/Markdown) with support for 100+ languages. Features advanced document parsing capabilities and is trusted by major AI projects like Dify and RAGFlow.
What it does
The installed package is a thin dispatch layer over a separate inference engine. It bundles thirteen single-purpose model classes and ten composed pipelines for reading text out of scanned pages, plus a client for Baidu's hosted job service and a server that AI agents can call over the Model Context Protocol. One import surface therefore covers three deployment shapes: models running in your own process, jobs submitted to a remote queue, and tools exposed to agents.
Why it's ranked here
Durability and breadth, not novelty, are the argument for it. The license is Apache 2.0 and the maintainer is an identified organisation with a contact address rather than an anonymous account. The problem it solves, turning scanned pages into text a program can index, is unglamorous and does not go away. What lifts it above other OCR wrappers is that the same option vocabulary drives local inference, the hosted job service and the agent server, so a prototype does not need a rewrite to become a service.
What's good
The local-versus-remote seam is unusually clean: the same option names appear in the Python pipelines, the command-line flags and the hosted-service options, so moving a workload between them is a configuration change rather than a rewrite. Failures come back as named error types for authentication, rate limits, polling timeouts, failed jobs and malformed responses, all exported from the top of the package. The agent server listens only on the local machine by default, refuses network flags unless you explicitly opt into HTTP, and masks error details. Documentation is maintained in English and Chinese side by side.
Tradeoffs
Almost none of the inference lives in this repository: the real engine is a separately pinned dependency, so your upgrade cadence follows another project's release train, and reading this code does not tell you how detection or recognition are implemented. The package's two dependency manifests disagree, because one serves the training code kept in the tree rather than the installed library. Linting is restricted to a narrow error-only subset, the default test run excludes resource-intensive tests, and the shipped test report is Chinese-only and lists six issues marked non-blocking across three client libraries.
How to use it well
Install only the extra you need rather than everything, since each extra pulls a different bundle of the underlying engine. For turning PDFs into Markdown, use one of the document pipelines and save each result as Markdown; for simple line-level jobs, call the detection and recognition models directly and skip pipeline overhead. Turn off orientation classification and page unwarping when inputs are already clean scans, as the quick-start examples do. Supply the hosted-service token through an environment variable rather than a command-line flag so it stays out of shell history. Code written for the 2.x line likely needs a rewrite before upgrading.
Technical notes+
pyproject.toml declares essentially one runtime dependency, paddlex[ocr-core]>=3.7.0,<3.8.0, and paddleocr/__init__.py re-exports thirteen model classes (including TextDetection, TableCellsDetection, SealTextDetection, ChartParsing, TextImageUnwarping) and ten pipelines (PPStructureV3, PaddleOCRVL, PPChatOCRv4Doc, PPDocTranslation, SealRecognition). The console entry point paddleocr.__main__:console_entry wraps main() and swallows BrokenPipeError; paddleocr/_utils/cli.py holds the shared loop, constructing the wrapper class from parsed args, iterating predict_iter, printing each result and calling save_all, with close() in a finally. paddleocr/_api_client/cli.py adds an api subcommand that submits a job and polls it, 300s per HTTP request and 600s total by default, returning a jobId with per-page prunedResult or markdownText; the token is best passed via PADDLEOCR_ACCESS_TOKEN. mcp_server/paddleocr_mcp/__main__.py builds inference from one of four providers (local, aistudio, qianfan, self_hosted) and serves it over stdio or streamable HTTP bound to 127.0.0.1:8000 with mask_error_details=True. The same option names (use_doc_unwarping, use_seal_recognition, text_rec_score_thresh) recur across pipelines, CLI flags and hosted-API options objects. Typed errors AuthError, RateLimitError, PollTimeoutError, JobFailedError and ResponseFormatError are exported top-level. requirements.txt lists shapely, pyclipper, albumentations and lmdb, absent from pyproject.toml, serving the in-tree training code. The flake8 pre-commit hook runs with --select=E9,F63,F7,F82,E721; pytest defaults to -m 'not resource_intensive'.
Observed
- License
- Apache License 2.0
- Language and packaging
- Python package; requires Python 3.8 or newer
- Interfaces
- Python library, CLI, hosted job API client, MCP server
- Public API surface
- 13 model classes and 10 pipeline classes re-exported from the package root
- MCP transport default
- stdio; HTTP mode binds to the local machine only
Read from README.md, pyproject.toml, requirements.txt, setup.py, paddleocr/__init__.py, paddleocr/__main__.py, paddleocr/_utils/cli.py, paddleocr/_pipelines/__init__.py, paddleocr/_models/__init__.py, paddleocr/_api_client/cli.py, mcp_server/paddleocr_mcp/__main__.py, docs/quick_start.en.md, docs/index.en.md, TEST_REPORT.md, .pre-commit-config.yaml.
What it can do
Convert PDF documents to structured JSON data
PDF file → JSON formatted text data
Convert PDF documents to Markdown format
PDF file → Markdown formatted text
Extract text from images using OCR
Image file → Plain text
Convert images to structured JSON data
Image file → JSON formatted text data
Convert images to Markdown format
Image file → Markdown formatted text
Parse documents for LLM consumption
PDF or image file → LLM-ready structured data
Perform multilingual text recognition
PDF or image with text in any of 100+ languages → Extracted text in original language
Tags
Tech Stack
Comments (0)
No comments yet
Editorially curated, with community endorsements as a secondary signal. Corrections welcome.