This page documents the paddleocr command-line interface (CLI): its entry point, available subcommands, universal and pipeline-specific arguments, output options, and PaddleX configuration file integration. The CLI lets you run inference on any supported pipeline directly from a shell without writing Python.
For the Python API that mirrors the same pipelines, see Python API Usage. For the configuration files the --paddlex_config flag points to, see Configuration System. For the package layout and PaddleX relationship, see Package Structure and PaddleX Integration.
The paddleocr executable is registered in pyproject.toml as:
console_entry in paddleocr/__main__.py parses the first positional argument as a subcommand name and dispatches to the corresponding pipeline executor.
Sources: pyproject.toml54-55
Diagram: CLI dispatch from console_entry to pipeline classes
Sources: pyproject.toml54-55 paddleocr/_pipelines/base.py paddleocr/_pipelines/pp_structurev3.py1-25 paddleocr/_pipelines/pp_chatocrv4_doc.py1-20 paddleocr/_pipelines/pp_doctranslation.py1-25
Diagram: Subcommand names mapped to their source files and Python classes
Sources: paddleocr/_pipelines/pp_structurev3.py28-144 paddleocr/_pipelines/pp_chatocrv4_doc.py23-83 paddleocr/_pipelines/pp_doctranslation.py24-99 paddleocr/_pipelines/table_recognition_v2.py25-80 paddleocr/_pipelines/seal_recognition.py1-30 paddleocr/_pipelines/formula_recognition.py1-30
Every subcommand accepts the following arguments. These are added by add_simple_inference_args in paddleocr/_utils/cli.py.
| Argument | Short | Description |
|---|---|---|
--input | -i | Path to input image, PDF, or directory of images |
--save_path | — | Directory where output files are saved |
--device | — | Inference device: cpu, gpu, gpu:0, gpu:0,1,2,3, npu, xpu, etc. |
--paddlex_config | — | Path to a PaddleX YAML pipeline configuration file |
The --device argument accepts comma-separated device IDs to enable parallel inference across multiple devices. See Parallel and Multi-Device Inference.
Sources: paddleocr/_pipelines/pp_structurev3.py16-21 paddleocr/_utils/cli.py docs/version3.x/pipeline_usage/instructions/parallel_inference.en.md1-30
Pipeline toggle flags (e.g. --use_doc_orientation_classify) are parsed via the str2bool helper in paddleocr/_utils/cli.py. Pass boolean values as True or False (case-insensitive):
Passing 0 or 1 also works. Omitting a flag leaves the value as the pipeline default.
Sources: paddleocr/_pipelines/pp_structurev3.py17 paddleocr/_pipelines/pp_chatocrv4_doc.py16
ocr — General OCR (PP-OCRv5)Runs text detection + recognition using the PaddleOCR pipeline.
| Key Argument | Description |
|---|---|
--use_doc_orientation_classify | Enable document-level orientation classification |
--use_doc_unwarping | Enable document image unwarping |
--use_textline_orientation | Enable text-line orientation classification |
--text_detection_model_name | Override default detection model |
--text_recognition_model_name | Override default recognition model |
--lang | Language code for model selection (e.g. en, ch) |
--ocr_version | OCR version: PP-OCRv3, PP-OCRv4, PP-OCRv5 |
pp_structurev3 — Document Structure AnalysisRuns the PPStructureV3 pipeline, producing Markdown and JSON output.
Selected arguments from PPStructureV3.__init__:
| Argument | Description |
|---|---|
--use_doc_orientation_classify | Enable document orientation module |
--use_doc_unwarping | Enable unwarping module |
--use_seal_recognition | Enable seal text recognition |
--use_table_recognition | Enable table recognition |
--use_formula_recognition | Enable formula recognition |
--use_chart_recognition | Enable chart recognition |
--use_region_detection | Enable region detection |
--layout_detection_model_name | Override layout detection model |
--text_detection_model_name | Override text detection model |
--text_recognition_model_name | Override text recognition model |
--lang | Language code |
--ocr_version | OCR version |
Sources: paddleocr/_pipelines/pp_structurev3.py28-139
pp_chatocrv4 — Intelligent Document UnderstandingRuns the PPChatOCRv4Doc pipeline. Requires document visual processing followed by chat-based extraction.
Selected arguments from PPChatOCRv4Doc.__init__:
| Argument | Description |
|---|---|
--use_doc_orientation_classify | Enable orientation classification |
--use_doc_unwarping | Enable unwarping |
--use_seal_recognition | Enable seal recognition |
--use_table_recognition | Enable table recognition |
--layout_detection_model_name | Override layout model |
--text_detection_model_name | Override text detection model |
Sources: paddleocr/_pipelines/pp_chatocrv4_doc.py23-78
pp_doctranslation — Document TranslationRuns the PPDocTranslation pipeline, which wraps PP-StructureV3 and adds LLM-based translation.
Selected arguments (superset of PP-StructureV3 arguments):
| Argument | Description |
|---|---|
--use_doc_orientation_classify | Enable orientation classification |
--use_doc_unwarping | Enable unwarping |
--use_formula_recognition | Enable formula recognition |
--use_chart_recognition | Enable chart recognition |
--chat_bot_config | LLM chat bot configuration |
Sources: paddleocr/_pipelines/pp_doctranslation.py24-99
doc_preprocessor — Document Image PreprocessingRuns orientation classification and/or unwarping on input images.
| Argument | Description |
|---|---|
--use_doc_orientation_classify | Enable orientation classification |
--use_doc_unwarping | Enable image unwarping |
--doc_orientation_classify_model_name | Override orientation model |
--doc_unwarping_model_name | Override unwarping model |
Sources: docs/version3.x/pipeline_usage/instructions/parallel_inference.en.md5-16
table_recognition_v2 — General Table RecognitionRuns the TableRecognitionPipelineV2 pipeline.
| Argument | Description |
|---|---|
--layout_detection_model_name | Override layout detection model |
--table_classification_model_name | Override table classification model |
--wired_table_structure_recognition_model_name | Model for wired tables |
--wireless_table_structure_recognition_model_name | Model for wireless tables |
Sources: paddleocr/_pipelines/table_recognition_v2.py25-80
seal_recognition — Seal Text RecognitionRuns the SealRecognition pipeline.
| Argument | Description |
|---|---|
--seal_text_detection_model_name | Override seal detection model |
--seal_det_limit_side_len | Detection limit side length |
--text_recognition_model_name | Override recognition model |
Sources: paddleocr/_pipelines/seal_recognition.py1-50
formula_recognition — Formula RecognitionRuns the FormulaRecognitionPipeline.
| Argument | Description |
|---|---|
--formula_recognition_model_name | Override formula recognition model |
--formula_recognition_batch_size | Batch size for inference |
--use_layout_detection | Enable layout detection |
Sources: paddleocr/_pipelines/formula_recognition.py1-50
text_detection and text_recognition — Individual ModulesThese subcommands run a single model module, not a full pipeline.
They accept --input, --save_path, --device, and model override arguments for the respective module.
Sources: docs/quick_start.en.md43-55
All subcommands accept --paddlex_config, which points to a PaddleX YAML pipeline configuration file. When specified, the file's contents become the default configuration for the entire pipeline run, taking priority over the built-in parameter defaults.
To generate a configuration file for a pipeline, use the export_paddlex_config_to_yaml Python method, or the paddlex CLI:
Pipeline registration names that correspond to CLI subcommands:
| CLI Subcommand | PaddleX Pipeline Name |
|---|---|
ocr | OCR |
pp_structurev3 | PP-StructureV3 |
pp_chatocrv4 | PP-ChatOCRv4-doc |
table_recognition_v2 | table_recognition_v2 |
formula_recognition | formula_recognition |
seal_recognition | seal_recognition |
doc_preprocessor | doc_preprocessor |
pp_doctranslation | PP-DocTranslation |
Sources: docs/version3.x/paddleocr_and_paddlex.en.md54-98 docs/version3.x/paddleocr_and_paddlex.en.md38-52
When --save_path is specified, pipelines save results to that directory. Output formats depend on the pipeline:
| Pipeline | Output Formats |
|---|---|
ocr | JSON, visualized image |
pp_structurev3 | JSON, Markdown, visualized image |
text_detection | JSON, visualized image |
text_recognition | JSON, visualized image |
formula_recognition | JSON, visualized image |
seal_recognition | JSON, visualized image |
table_recognition_v2 | JSON, HTML table, visualized image |
If --save_path is not specified, results are printed to stdout.
Sources: docs/quick_start.en.md37-60 paddleocr/_pipelines/pp_structurev3.py145-220
The --device flag accepts a comma-separated list of device identifiers. When multiple devices are given, the pipeline creates one internal instance per device and distributes input items across them:
Valid device string formats:
| Format | Meaning |
|---|---|
cpu | CPU inference |
gpu | Default GPU |
gpu:0 | GPU device 0 |
gpu:0,1,2,3 | GPUs 0–3, parallel |
npu | Ascend NPU |
xpu | Kunlunxin XPU |
Sources: docs/version3.x/pipeline_usage/instructions/parallel_inference.en.md1-31
Diagram: Argument resolution order at runtime
If a --paddlex_config file is specified and a CLI flag is also provided, the CLI flag always wins. Parameters absent from both fall back to the pipeline's compiled defaults.
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.