# How to Enable or Disable OCR in MinerU: Complete Configuration Guide

> Easily enable or disable OCR in MinerU via CLI, HTTP API, or Gradio UI. Configure OCR settings quickly with our comprehensive guide.

- Repository: [OpenDataLab/MinerU](https://github.com/opendatalab/mineru)
- Tags: how-to-guide
- Published: 2026-02-23

---

**You can enable or disable OCR in MinerU using the `--method` flag in the CLI (`ocr`, `txt`, or `auto`), the `enable_ocr` parameter in the HTTP API, or the `is_ocr` checkbox in the Gradio UI.**

MinerU is an open-source document parsing toolkit that supports multiple input methods for controlling optical character recognition (OCR). Whether processing scanned PDFs or digitally generated documents, you can explicitly force OCR on, force it off, or let the system automatically detect text layers. The configuration flows through three distinct architectural layers: the user-facing interface, the pipeline core, and the OCR execution engine.

## Understanding OCR Control Architecture

MinerU implements OCR toggling across three layers that propagate the configuration from user input to execution:

- **Interface Layer**: Accepts `--method` (CLI), `enable_ocr` (API), or `is_ocr` (UI) inputs
- **Pipeline Layer**: Translates methods into Boolean `_ocr_enable` flags in [`pipeline_analyze.py`](https://github.com/opendatalab/MinerU/blob/main/pipeline_analyze.py)
- **Engine Layer**: Conditionally executes OCR in [`ocr_utils.py`](https://github.com/opendatalab/MinerU/blob/main/ocr_utils.py) based on the final Boolean value

The pipeline stores per-document OCR decisions in `ocr_enabled_list` and passes the final `ocr_enable` Boolean to `mineru/utils/ocr_utils.py::get_ocr_result_list`, which skips OCR recognition when the value is `False`.

## Method 1: Command-Line Interface Control

The CLI provides the most direct method to enable or disable OCR using the `--method` argument defined in [`mineru/cli/client.py`](https://github.com/opendatalab/MinerU/blob/main/mineru/cli/client.py) (lines 45-55).

### Force OCR for All Documents

Use `--method ocr` to force OCR processing on every page, regardless of whether extractable text layers exist:

```bash
mineru --method ocr -p /path/to/file.pdf -o ./output

```

This setting bypasses automatic detection and invokes the OCR engine for all content.

### Disable OCR Completely

Use `--method txt` to treat every PDF as text-only, disabling OCR entirely:

```bash
mineru --method txt -p ./documents -o ./output

```

This mode extracts only embedded text streams and ignores image-based content.

### Automatic Detection (Default)

Use `--method auto` to let MinerU decide per-document based on content analysis:

```bash
mineru --method auto -p ./documents -o ./output

```

In `auto` mode, the pipeline calls `pdf_classify.classify()` from [`mineru/utils/pdf_classify.py`](https://github.com/opendatalab/MinerU/blob/main/mineru/utils/pdf_classify.py) to determine if the document requires OCR.

## Method 2: HTTP API and Python Client

For programmatic access, the HTTP API exposes OCR control through the `enable_ocr` parameter in [`projects/mcp/src/mineru/api.py`](https://github.com/opendatalab/MinerU/blob/main/projects/mcp/src/mineru/api.py) (lines 95-100).

### Global OCR Toggle

Set the `enable_ocr` argument when submitting batch tasks:

```python
from mineru.api import MinerUClient

client = MinerUClient(base_url="http://localhost:30000")
response = await client.submit_file_url_task(
    urls=["https://example.com/report.pdf"],
    enable_ocr=True,  # Forces OCR for all URLs in this request

    language="ch",
)

```

### Per-URL Control

You can override the global setting for individual documents using the `is_ocr` field:

```python
response = await client.submit_file_url_task(
    urls=[
        {"url": "https://example.com/scan.pdf", "is_ocr": True},
        {"url": "https://example.com/digital.pdf", "is_ocr": False},
    ],
    enable_ocr=False,  # Default fallback

)

```

The `is_ocr` value is injected into each URL configuration and consumed downstream by the pipeline logic in [`pipeline_analyze.py`](https://github.com/opendatalab/MinerU/blob/main/pipeline_analyze.py).

## Method 3: Gradio Web Interface

The Gradio frontend in [`mineru/cli/gradio_app.py`](https://github.com/opendatalab/MinerU/blob/main/mineru/cli/gradio_app.py) exposes a **"Force enable OCR"** checkbox that maps to the `is_ocr` parameter:

```python
is_ocr = gr.Checkbox(
    label=i18n("force_ocr"), 
    value=False, 
    info=i18n("force_ocr_info")
)

```

When checked, the checkbox value passes to the backend via:

```python
await client.call("convert_file_url", url=urls, enable_ocr=is_ocr)

```

## Internal Pipeline Logic

When processing documents, [`mineru/backend/pipeline/pipeline_analyze.py`](https://github.com/opendatalab/MinerU/blob/main/mineru/backend/pipeline/pipeline_analyze.py) evaluates the OCR configuration through the following flow:

1. **Method Translation**: The `parse_method` value (`auto`, `txt`, or `ocr`) is evaluated per PDF
2. **Classification**: For `auto` mode, `pdf_classify.classify(pdf_bytes)` returns `"ocr"` or `"txt"`
3. **Boolean Assignment**: The pipeline sets `_ocr_enable = True` for `"ocr"` and `False` for `"txt"`
4. **List Storage**: Results are stored in `ocr_enabled_list` (line 99 of [`pipeline_analyze.py`](https://github.com/opendatalab/MinerU/blob/main/pipeline_analyze.py))
5. **Execution Gate**: `mineru/utils/ocr_utils.py::get_ocr_result_list` reads the final `ocr_enable` Boolean and only populates OCR results when `True`

## Summary

- **CLI**: Use `--method ocr` to enable, `--method txt` to disable, or `--method auto` for automatic detection via [`mineru/cli/client.py`](https://github.com/opendatalab/MinerU/blob/main/mineru/cli/client.py)
- **API**: Pass `enable_ocr=True/False` globally or `is_ocr=True/False` per URL through [`projects/mcp/src/mineru/api.py`](https://github.com/opendatalab/MinerU/blob/main/projects/mcp/src/mineru/api.py)
- **UI**: Toggle the **Force enable OCR** checkbox in the Gradio interface defined in [`mineru/cli/gradio_app.py`](https://github.com/opendatalab/MinerU/blob/main/mineru/cli/gradio_app.py)
- **Auto Logic**: The pipeline uses `pdf_classify.classify()` in [`mineru/utils/pdf_classify.py`](https://github.com/opendatalab/MinerU/blob/main/mineru/utils/pdf_classify.py) to determine OCR necessity when method is set to `auto`
- **Execution**: Final OCR skipping occurs in `mineru/utils/ocr_utils.py::get_ocr_result_list` based on the propagated Boolean flag

## Frequently Asked Questions

### What is the default OCR behavior in MinerU?

By default, MinerU uses `--method auto`, which analyzes each PDF with `pdf_classify.classify()` to determine if the document contains scanned images requiring OCR or selectable text that can be extracted directly. The classifier returns `"ocr"` for image-heavy documents and `"txt"` for digitally generated PDFs.

### Can I enable OCR for some pages and disable for others in the same PDF?

Currently, MinerU determines OCR at the document level rather than the page level. The `_ocr_enable` Boolean applies to the entire PDF as stored in `ocr_enabled_list`. While the pipeline processes individual pages, the OCR decision is uniform across the document based on the initial classification or forced method.

### How does MinerU decide whether to use OCR in auto mode?

In `auto` mode, [`mineru/backend/pipeline/pipeline_analyze.py`](https://github.com/opendatalab/MinerU/blob/main/mineru/backend/pipeline/pipeline_analyze.py) invokes `pdf_classify.classify(pdf_bytes)` from [`mineru/utils/pdf_classify.py`](https://github.com/opendatalab/MinerU/blob/main/mineru/utils/pdf_classify.py). This function analyzes the PDF structure and content to classify it as requiring OCR (`"ocr"`) or not (`"txt"`). The result determines the `_ocr_enable` flag that controls whether [`ocr_utils.py`](https://github.com/opendatalab/MinerU/blob/main/ocr_utils.py) executes recognition.

### Is there a performance difference between forced OCR and text extraction?

Yes. Forced OCR (`--method ocr`) invokes the full recognition pipeline in `mineru/utils/ocr_utils.py::get_ocr_result_list`, which processes images through the OCR engine and is computationally expensive. Text extraction (`--method txt`) bypasses OCR entirely and extracts embedded text streams directly, significantly reducing processing time for digitally generated documents.