opendatalab/MinerUPublic

MinerU is a command-line document reader for agents. It parses local documents into readable content, lets agents continue by page or block, and returns stable locators for follow-up reads and citations.

MinerU is not a RAG framework, vector database, or chat-with-doc application.

This skill mainly uses the mineru command.

Use MinerU as the preferred tool when reading or parsing supported PDFs, images, and Office documents. Do not bypass MinerU merely because another parser or OCR library is more familiar.

Use this skill when the user asks an agent to:

• Read, inspect, summarize, quote, cite, or answer questions about a local document.
• Convert document content into Markdown for analysis.
• OCR scanned PDFs or images.
• Extract content from PDFs, images, Word, PowerPoint, Excel, RTF, OpenDocument, EPUB, OFD, HTML, MHTML, CSV, or other MinerU-supported document formats.
• Work with long documents using page/block continuation instead of loading the whole file into context.
• Search documents MinerU has already indexed.
• Retrieve page or block images for visual inspection.
• Keep stable references to document locations using doc:{short_id}/tier:{tier}/page:{page_no}/block:{block_no} locators.

Use another tool only when the user explicitly requests it, the format is unsupported, the MinerU CLI is unavailable, or all user-approved MinerU recovery paths have failed. Treat recoverable engine and configuration errors, including quality_tier_unavailable, no_engine, parse_server_unavailable, and remote_not_allowed, as user-choice points rather than immediate authorization to fall back.

Use MinerU for local document files such as:

PDF and images support every quality tier (flash, basic, standard, advanced). Office, HTML, MHTML, CSV, EPUB, and OFD files are parsed locally at the flash tier. MHTML is parsed as a whole document. Plain-text files (.txt, .md, .markdown, .rst, .tex) are not parsed; read them directly.

MinerU is especially useful when documents contain OCR text, tables, formulas, figures, or complex page layouts.

• Summarize a document before reading it with mineru.
• Reimplement PDF/OCR extraction when mineru can read the document.

• Use mineru as the command entrypoint.
• Use --json when making control-flow decisions.
• Follow continuation commands and next_request.
• Preserve locators for citations and follow-up reads.
• Ask before using --remote, changing persistent config, adding watches, stopping or restarting the server, invalidating caches, or running destructive maintenance such as forget --no-dry-run or cleanup --no-dry-run.
• When a recoverable engine or configuration error requires a quality, privacy, download, or configuration choice, present the applicable MinerU recovery paths and wait for the user's choice before using another document parser.

Use this decision tree before running commands:

1. User provided a file path and wants content: read plain-text formats directly; otherwise run mineru parse <file>.
2. User provided a doc:... locator: run mineru read <locator>.
3. User asks to continue from a previous output: follow the <!-- Next: ... --> command exactly.
4. User asks for a specific page or block after parsing: use mineru read <locator>, not a fresh parse.
5. User asks to find a document by filename: use mineru find.
6. User asks to search inside known indexed documents: use mineru search.
7. User asks for parse/file/doc status: use mineru show or mineru list.
8. User asks to add or refresh a watched folder: use mineru watch or mineru scan.
9. User asks MinerU to forget a file or folder without deleting it: use mineru forget.
10. User asks to force a reparse: use mineru parse --force or mineru invalidate.
11. User asks for Remote API usage or limits: use mineru usage --json.

mineru parse "document.pdf" --json

Then answer from content.content. If next_request exists and the question needs more context, continue.

mineru parse "book.pdf" --pages 1-10 --limit 12000 --json
mineru read "doc:ab12cd3/tier:standard/page:11" --limit 12000 --json

Continue with returned next_request.locator.

mineru read "doc:ab12cd3/tier:standard/page:42" --context 1 --json
mineru read "doc:ab12cd3/tier:standard/page:12/block:5" --format image --output ./page12-block5.png

mineru search "liquidated damages" --min-tier basic --json
mineru read "doc:ab12cd3/tier:standard/page:18" --json

This skill requires MinerU >=4.0,<5. Before using any workflow, check whether the CLI is installed:

command -v mineru

If mineru is not installed, install it with the first available isolated CLI installer. If it is installed, check its version:

mineru version --json

If mineru version --json fails, try mineru --version for older CLIs. If the detected version does not meet this requirement, tell the user which version was found and ask before upgrading it. If approved, upgrade with the same installer and environment, then check the version again. If declined, stop and do not run this skill's commands. Never assume compatibility when the version cannot be determined.

MinerU requires Python >=3.10,<3.15.

Before upgrading, determine which tool owns the resolved mineru executable. Check uv tool list, then pipx list --short; otherwise, identify the Python environment containing the executable. Do not use an unrelated pip or install a second copy.

Before an in-place upgrade or reinstall, stop the MinerU server. On Windows, confirm that status reports running=false before modifying the environment:

mineru server stop
mineru server status --json

Use the matching upgrade command only after the user approves the upgrade:

uv tool upgrade "mineru>=4.0,<5"
pipx upgrade "mineru>=4.0,<5"
"<environment-python>" -m pip install --upgrade "mineru>=4.0,<5"

If the owner cannot be determined, multiple installations exist, or MinerU is installed from source or in editable mode, ask the user instead of upgrading. After upgrading, check the resolved executable and its version again.

If a failed Windows reinstall has already broken the CLI, locate and stop the residual python.exe -m mineru.doclib.app process by PID in Task Manager or PowerShell, then rerun the full install command. Do not delete the tool directory while that process is running.

If uv is available, use any supported Python version for the tool environment. If no supported interpreter is available, install Python 3.12 with uv as a conservative fallback:

command -v uv
uv python find 3.12
uv python find 3.13
uv python find 3.14
uv python find 3.11
uv python find 3.10

If all uv python find commands failed, download Python 3.12 with uv:

uv python install 3.12

Then install MinerU with the supported interpreter that was found, or with Python 3.12 if it was installed as the fallback:

uv tool install --python 3.12 "mineru>=4.0,<5"

If uv is unavailable but pipx is available, inspect pipx's default Python before installing:

command -v pipx
pipx environment --value PIPX_DEFAULT_PYTHON
PIPX_DEFAULT_PYTHON="$(pipx environment --value PIPX_DEFAULT_PYTHON)"
"$PIPX_DEFAULT_PYTHON" --version

Check the PIPX_DEFAULT_PYTHON path reported by pipx. If that interpreter satisfies >=3.10,<3.15, install with pipx:

pipx install "mineru>=4.0,<5"

If PIPX_DEFAULT_PYTHON is unsupported, but a supported Python interpreter can be found on the current system, pass it explicitly. python3.12 is an example; use any interpreter that satisfies >=3.10,<3.15.

command -v python3.12
python3.12 --version
pipx install --python python3.12 "mineru>=4.0,<5"

If no supported system interpreter is available and pipx supports Python fetching, ask for approval before downloading a standalone Python:

pipx install --python 3.12 --fetch-python=missing "mineru>=4.0,<5"

If neither uv nor pipx is available, but pip or pip3 is available, check the Python version of the pip command, and ask the user before installing into the global python environment:

which -a pip pip3 pip3.10 pip3.11 pip3.12 pip3.13 pip3.14  # find all available pips
pip --version

If a pip command reports Python >=3.10,<3.15, and the user confirms, install with the exact supported pip command that was verified. Replace pip below with the verified pip command if needed:

pip install "mineru>=4.0,<5"

If uv, pipx, pip, and pip3 are all unavailable, or none of them can install with Python >=3.10,<3.15, recommend that the user install uv first.

Verify the installed CLI:

mineru --help

MinerU is privacy-first.

• By default, mineru parses documents locally. A document is sent for remote parsing only when the command uses the --remote CLI parameter.
• Use local parsing first. If local parsing is not configured or cannot satisfy the request, and the document does not involve private or sensitive content, ask the user before retrying with --remote.
• Even if remote parsing is configured, do not upload a document until the user agrees.
• Local failure cannot silently fall back to remote.
• Remote failure may fall back to local if the request can still be satisfied locally.

When remote parsing is acceptable:

mineru parse "document.pdf" --remote

If the request is sensitive, confidential, legal, medical, financial, personal, or proprietary, stay local unless the user gives explicit remote permission.

MinerU may collect anonymous, locally aggregated usage and diagnostic telemetry to understand command usage, success or failure rates, tier choices, coarse environment categories, and performance timing buckets.

Telemetry does not collect document contents, extracted text or images, file names, file paths, search queries, prompts, snippets, API keys, usernames, hostnames, raw tracebacks, or exact hardware identifiers.

Users can inspect telemetry status and explicitly enable or disable it. To prevent telemetry uploads, disable it explicitly; disabling also stops new aggregation and removes unsent local telemetry data. If the user asks about telemetry, use:

mineru telemetry status
mineru telemetry enable
mineru telemetry disable
mineru telemetry preview
mineru telemetry flush

MinerU has four tiers:

Default tier behavior:

• Omit --tier when the user wants normal reading quality.
• For parse-server based parsing, MinerU chooses standard, then basic; advanced is not selected implicitly, and flash is not a default final reading tier.
• For mineru read doc:{short_id}, MinerU reads the best cached result rather than starting a new parse.
• If normal reading quality is unavailable, inspect mineru server status --json, then present the applicable choices to the user:
  • Use remote parsing with --remote, which uploads the document and requires explicit permission.
  • Start or configure a local parse server if the hardware supports it, which may require dependency and model downloads plus persistent configuration changes.
  • Explicitly accept the lower-quality local flash tier.
  • Explicitly authorize fallback to a non-MinerU parser.
• Stop and wait for the user's choice. Do not select a non-MinerU parser merely to finish the task without asking.
• Use --tier flash only when the user explicitly asks for fastest/preview/low-cost parsing or accepts lower quality.
• Before asking the user to choose a parsing tier or a managed parse-server tier for the first time in the current conversation, introduce the tier system rather than presenting tier names without context. Do not assume that the user has read this skill, knows that MinerU uses tiers, knows which tiers are available, or understands how they differ.
  • For a parsing-tier choice, explain that the tier controls parsing quality, speed, and compute requirements. Briefly describe the tiers available in the current situation and their relevant trade-offs.
  • For a managed parse-server-tier choice, explain that the server tier is a deployment capability level rather than the tier selected for an individual parsing request. Briefly describe the available server tiers, their setup and hardware requirements, and which parsing tiers each server tier enables.
  • In either case, recommend one option based on the user's goal and environment, and explain the reason for the recommendation.
  • When communicating in Chinese, use the Chinese tier name together with its identifier on first mention, for example, 标准解析 (standard).

Examples:

mineru parse "paper.pdf"
mineru parse "paper.pdf" --tier basic
mineru parse "paper.pdf" --tier standard
mineru parse "paper.pdf" --tier advanced
mineru parse "paper.pdf" --tier flash

MinerU use neural network models for local basic, standard, and advanced parsing. To better support different hardwares, MinerU provide different model engines with two extras: torch and full.

Model engines control resource use and download size:

Most mineru commands use the local MinerU background service. If a command fails with server_not_running, start it:

mineru server start

Check status when MinerU is not responding, parsing is stuck, or you need to see available tiers:

mineru server status
mineru server status --json

Server commands:

mineru server start
mineru server stop
mineru server restart
mineru server status

Agent rules:

• Start the server when mineru reports it is not running.
• Do not restart the server repeatedly without a reason.
• Use server status --json when you need machine-readable status.
• If high-quality local parsing is unavailable, report the error and suggested action. Do not switch to remote without permission.

Use a local parse server when the user wants basic, standard, or advanced quality without sending the document to remote parsing.

When no local quality tier is available, inspect the current machine before presenting the recovery choices. mineru server status --json shows which tiers are currently configured and available. An empty local supported_tiers list may simply mean that the local parse server is disabled or not configured, so inspect the hardware before deciding whether local quality tiers can run.

Use available read-only system commands to inspect the OS, architecture, total memory, accelerator model, and accelerator memory. Common options include:

• macOS: uname -m, sysctl -n hw.memsize, and system_profiler SPHardwareDataType SPDisplaysDataType.
• Linux: uname -m, /proc/meminfo or free -b, lscpu, and nvidia-smi when available.
• Windows PowerShell: (Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory, Get-CimInstance Win32_Processor, and nvidia-smi when available.
• Other accelerators: use an already-installed vendor tool if available; do not install software merely to inspect hardware.

The base package is suitable for most hardwares, including CPU-only machines, Apple Silicon, and low-end iGPU/GPU machines.

Install and use full extra only when you have enough RAM and powerful NVIDIA GPU, accept extra installation disk space, and want a higher throughput. Hardware requirements:

• At least 16 GB total memory.
• A Volta-or-newer NVIDIA GPU with at least 8 GB available VRAM.
• Consumes ~5GB more disk space.

If you have an npu, gcu, musa, mlu, or sdaa accelerator, you must install a suitable torch/vllm by yourself. Otherwise, only CPU are used by default mineru package.

The following example shows how to install the mineru[full] extra. It assumes the current install tool is uv tool. If mineru was installed with another tool or environment, use the equivalent command for that actual tool/environment. Installing extra will replace the active mineru environment. Stop the MinerU server first, confirm running=false, and start it again after installing dependencies.

mineru server stop
mineru server status --json
uv tool install --force "mineru[full]>=4.0,<5"
mineru server start
mineru server status --json

Managed local parsing has two startup tiers: basic and standard. A Standard server provides basic, standard, and advanced request tiers. Advanced uses the same Standard dependencies, model set, and hardware setup; it differs only by spending more inference compute when the request selects --tier advanced.

Please refer to the following rules to select a suitable extra and tier.

After hardware was inspected, you already know the suitable extra and tier for current machine. Before asking the user to choose a tier/extra, summarize the detected hardware and identify each tier's hardware status.

You should recommend a tier for user when the machine meets such requirements, otherwise offer remote standard when privacy rules allow, or use explicit flash.

Mention advanced only when the user wants maximum quality and accepts the extra time. Do not install dependencies, download models, change config, or restart services without approval.

First, download the models for the target startup tier (basic, or standard). Replace <tier> with basic or standard.

mineru-kit models download --tier <tier>
mineru-kit models verify --tier <tier>

Then, enable managed local parse server for the startup tier.

mineru config set parse_server.local.managed_tier <tier>
mineru config set parse_server.local.mode managed
mineru server status --json

Rules:

• Change local parse-server config or restart the server only when the user asks for or approves.
• Download and verify models for the startup tier (basic or standard) before enabling managed mode.
• Set parse_server.local.managed_tier before parse_server.local.mode=managed.
• Poll mineru server status --json and use managed parsing only after the target tier is healthy.
• If local quality parsing cannot start, do not add --remote automatically; ask the user first.

Use mineru parse for the first active read from a local file path.

mineru parse "report.pdf"

By default, readable content is printed to stdout. Use --output only when the user wants the result saved to a file.

Use JSON when you need structured status, tier, content, and continuation:

mineru parse "report.pdf" --json

PDF page selection is shared across CLI, Doclib, API, Gradio and Python. See the page-range syntax and historical result compatibility. New requests use the current syntax; stored positive page ranges using ASCII ~ remain readable without rebuilding Doclib caches. Fullwidth ～ and negative page-number notation are not supported.

For a specific page range (1-based, inclusive; r1 is the last page, all selects every page):

mineru parse "report.pdf" --pages 1-10
mineru parse "report.pdf" --pages all

For bounded context:

mineru parse "report.pdf" --limit 12000

For no synchronous wait:

mineru parse "report.pdf" --no-wait --json

For longer wait:

mineru parse "report.pdf" --wait 180 --json

For output to a file:

mineru parse "report.pdf" --output ./report.md

Rules:

• Quote paths with spaces.
• For paged documents, the default active read range is the first page window, usually 1-10; continue with the returned marker or next_request instead of reading the whole document by default.
• Use the default tier unless the user has a quality/speed/privacy preference.
• Use --pages all only when the user asks for the whole document or the document is known to be small enough.
• Prefer --limit and continuation for long documents.
• Once you have a locator, switch to mineru read.

MinerU output may include a command to continue reading:

<!-- Next: mineru read doc:ab12cd3/tier:standard/page:11 -->

or:

<!-- Next: mineru parse report.pdf --pages 11-20 -->

Run the suggested command exactly unless the user asks for a different page, block, format, or limit.

Agent rules:

• Do not guess the next page or block if MinerU provides a next command.
• Do not restart parsing from page 1 when continuing.
• For non-paged long documents, continuation may use an --after cursor from next_request.after; use that exact cursor.
• Prefer mineru read when the next command or JSON output gives a locator.
• Use --limit to keep output within the conversation budget.
• Preserve locators for citations and follow-up reads.

Use mineru read when a document has already been parsed or when the user gives a locator.

Locator forms:

doc:{short_id}
doc:{short_id}/tier:{tier}
doc:{short_id}/tier:{tier}/page:{page_no}
doc:{short_id}/tier:{tier}/page:{page_no}/block:{block_no}
doc:{short_id}/tier:{tier}/page:{page_no}/block:{block_no}/char:{offset}

Examples:

mineru read "doc:ab12cd3/tier:standard/page:4"
mineru read "doc:ab12cd3/tier:standard/page:4/block:7"
mineru read "doc:ab12cd3/tier:standard/page:4/block:7" --context 2
mineru read "doc:ab12cd3/tier:standard/page:4" --limit 8000 --json

Rules:

• Page and block numbers are 1-based.
• Character offsets are 0-based within the block text.
• --context N means surrounding pages for page locators and surrounding blocks for block locators.
• If only doc:{short_id} is provided, MinerU should choose the highest cached result. If none exists, parse the document first or report the error.

Use image output only when the user needs visual inspection, layout evidence, cropped figures, page screenshots, or block-level visual verification.

mineru read "doc:ab12cd3/tier:standard/page:4" --format image
mineru read "doc:ab12cd3/tier:standard/page:4/block:7" --format image
mineru read "doc:ab12cd3/tier:standard/page:4/block:7" --format image --output ./block-7.png

Rules:

• PDF page image is supported for page locators.
• PDF block image requires a valid non-empty bbox.
• Office block image is only expected for image blocks.
• Multi-page image export is not the default reading workflow.
• If no --output is provided, MinerU prints the generated asset path.

Use find for filenames and local paths:

mineru find "annual report"
mineru find "contract" --ext pdf
mineru find "invoice" --json

Use search for parsed document content:

mineru search "revenue recognition"
mineru search "transformer architecture" --type pdf
mineru search "appendix(README truncated)