MinerU

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.

When To Use MinerU

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, 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.

Supported Inputs

Use MinerU for local document files such as:

Type	Extensions
PDF	`.pdf` , including scanned PDFs and academic papers
Images	`.png` , `.jpg` , `.jpeg` , `.webp` , `.gif` , `.bmp` , `.tiff` , `.jp2`
Word	`.doc` , `.docx`
PowerPoint	`.ppt` , `.pptx`
Excel	`.xls` , `.xlsx`
Rich text	`.rtf`
OpenDocument	`.odt` , `.ods` , `.odp`
EPUB	`.epub` , parsed as a full document in OPF spine order with source internal links preserved
OFD	`.ofd`
HTML	`.html` , `.htm` , `.shtml`
CSV / TSV	`.csv` , `.tsv`

PDF and images support every quality tier (

flash

basic

standard

advanced

). Office, HTML, CSV, EPUB, and OFD files are parsed locally at the

flash

tier. 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.

Do Not

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

Agent Contract

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.

Core Decision Tree

Use this decision tree before running commands:

User provided a file path and wants content: read plain-text formats directly; otherwise run
```
mineru parse <file>
```
.
User provided a
```
doc:...
```
locator: run
```
mineru read <locator>
```
.
User asks to continue from a previous output: follow the
```

```
command exactly.
User asks for a specific page or block after parsing: use
```
mineru read <locator>
```
, not a fresh parse.
User asks to find a document by filename: use
```
mineru find
```
.
User asks to search inside known indexed documents: use
```
mineru search
```
.
User asks for parse/file/doc status: use
```
mineru show
```
or
```
mineru list
```
.
User asks to add or refresh a watched folder: use
```
mineru watch
```
or
```
mineru scan
```
.
User asks MinerU to forget a file or folder without deleting it: use
```
mineru forget
```
.
User asks to force a reparse: use
```
mineru parse --force
```
or
```
mineru invalidate
```
.
User asks for Remote API usage or limits: use
```
mineru usage --json
```
.

Common Workflows

First read from a file

bash

mineru parse "document.pdf" --json

Then answer from

content.content

. If

next_request

exists and the question needs more context, continue.

Continue progressively

bash

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

Read or inspect a known location

bash

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

Search local library, then read

bash

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

Installation And Setup

This skill requires MinerU

>=4.0,<5

. Before using any workflow, check whether the CLI is installed:

bash

command -v mineru

mineru

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

bash

mineru version --json

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

Upgrade An Existing Installation

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:

bash

mineru server stop
mineru server status --json

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

bash

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.

Install with

uv

(preferred)

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:

bash

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

bash

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:

bash

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

Install with

pipx

uv

is unavailable but

pipx

is available, inspect

pipx

's default Python before installing:

bash

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

bash

pipx install "mineru>=4.0,<5"

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

bash

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:

bash

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

Install with global

pip

If neither

uv

nor

pipx

is available, but

pip

pip3

is available, check the Python version of the

pip

command, and ask the user before installing into the global python environment:

bash

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:

bash

pip install "mineru>=4.0,<5"

If No Supported Installer Is Available

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.

After Installation

Verify the installed CLI:

bash

mineru --help

Privacy Rules

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:

bash

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.

Telemetry

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:

bash

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

Quality Tiers

MinerU has four tiers:

Tier	Chinese name	Quality and speed	Use for
`flash`	极速解析	Lowest quality; fastest	Discovery, preview, and indexing; never default final reading quality
`basic`	基础解析	Basic quality; moderate speed	Private local reading or lower-resource local parsing
`standard`	标准解析	Standard high quality; similar speed to `basic` on suitable hardware	Default for normal active reading and complex documents
`advanced`	高级解析	Standard quality on ordinary documents and better quality on difficult documents; slowest	Difficult documents and maximum-quality work when the user accepts a longer wait

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:

bash

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

Model Engines with Extras

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

Extra	Model engines installed	How to install
(base)	ONNX + llama.cpp	Already in `mineru` base module
`torch`	ONNX + PyTorch + llama.cpp	Install with `mineru[torch]` (Apple Silicon already installed this extra in base package.)
`full`	ONNX + PyTorch + llama.cpp + vLLM/lmdeploy/mlx	Install with `mineru[full]`

Model engines control resource use and download size:

Tier	Model engines	Model download	Min RAM required	Accelerator
`basic`	ONNX	~0.8 GB	2GB	None (CPU works)
`basic`	PyTorch	~0.8 GB	8 GB	GPU/MPS recommended
`standard` / `advanced`	ONNX + llama.cpp	~2 GB	8 GB	CPU works, Vulkan recommended
`standard` / `advanced`	PyTorch + llama.cpp	~2 GB	16 GB	GPU/MPS required, 8 GB+ VRAM
`standard` / `advanced`	PyTorch + vLLM/lmdeploy/mlx	~3 GB	16 GB	GPU/MPS required, 8 GB+ VRAM

Server Rules

Most

mineru

commands use the local MinerU background service. If a command fails with

server_not_running

, start it:

bash

mineru server start

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

bash

mineru server status
mineru server status --json

Server commands:

bash

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.

Local Parse Server

Use a local parse server when the user wants

basic

standard

, or

advanced

quality without sending the document to remote parsing.

Inspect Local Hardware

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

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.

Choose Extra

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.

bash

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

Choose Local Tier

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.

Hardware	Recommended startup tier	Model engines	Extra
MacOS with Apple Silicon	`standard`	PyTorch + llama.cpp	`torch` (already installed)
MacOS with Intel CPU	`basic`	ONNX	(base)
Linux/Windows with NVIDIA GPU and 8GB+ VRAM	`standard`	PyTorch + vLLM/lmdeploy	`full`
Linux/Windows with NVIDIA GPU and 4GB+ VRAM	`basic`	PyTorch	`torch`
Linux/Windows with other accelerator	(depends)	PyTorch / vLLM	install custom torch/vllm by yourself
Linux/Windows with modern iGPU	`standard`	ONNX + llama.cpp	(base)
Linux/Windows w/o modern accelerator	`basic`	ONNX	(base)

Recommend and Ask

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.

Configure Managed Parse Server

First, download the models for the target startup tier (

basic

, or

standard

). Replace

<tier>

with

basic

standard

bash

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

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

bash

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.

First Read From A File

Use

mineru parse

for the first active read from a local file path.

bash

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:

bash

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):

bash

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

For bounded context:

bash

mineru parse "report.pdf" --limit 12000

For no synchronous wait:

bash

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

For longer wait:

bash

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

For output to a file:

bash

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
```
.

Continue Reading

MinerU output may include a command to continue reading:

text

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

or:

text

<!-- 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.

Read By Locator

Use

mineru read

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

Locator forms:

text

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:

bash

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.

Read Page Or Block Images

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

bash

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.

Search And Find

Use

find

for filenames and local paths:

bash

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

Use

search

for parsed document content:

bash

mineru search "revenue recognition"
mineru search "transformer architecture" --type pdf
mineru search "appendix" --min-tier basic --limit 10 --json

Rules:

```
find
```
does not search document content.
```
search
```
only searches content MinerU has already indexed.
If search returns only low-quality or
```
flash
```
snippets and the user needs an answer, parse or read the target document at default quality before relying on the content.
Do not repeat sensitive search snippets in final output unless needed to answer the user.

Inspect Status

Use

show

for one resource:

bash

mineru show file "report.pdf"
mineru show file "report.pdf" --json
mineru show parse 123 --json
mineru show doc "<sha256>" --json
mineru show scan 456 --json

Use

list

for collections:

bash

mineru list docs
mineru list files --ext pdf
mineru list parses --status parsing
mineru list scans --status running
mineru list docs --json

Rules:

Use
```
show file
```
after parse timeout to see active parses and cached tiers.
Use
```
list parses
```
to inspect queued, parsing, failed, or done parse tasks.
Use JSON modes when you need structured output.

Watch, Scan, And Local Library Maintenance

Use

scan

for one-time discovery or refresh:

bash

mineru scan "~/Documents/report.pdf"
mineru scan "~/Documents/project"
mineru scan "~/Documents/project" --no-wait --json

Use

watch

for persistent folders:

bash

mineru watch add "~/Documents"
mineru watch add "/Volumes/Archive" --removable
mineru watch list
mineru watch rescan "~/Documents"
mineru watch remove "~/Documents"

Watch rules:

Watch is for discovery and search indexing.
Watch defaults to
```
flash
```
.
Watch results are not final reading quality.
Active reading should still use
```
mineru parse
```
or
```
mineru read
```
.
The CLI normalizes local path arguments with user-home expansion, absolute paths, and normalized separators.
For
```
watch rescan
```
and
```
watch remove
```
, use either a watch id or the watch root path.
Watch will not trigger remote parsing unless a parsing rule explicitly allows remote.

Use parsing rules only when the user wants automatic parse policy for paths:

bash

mineru config parsing-rules add "*/papers/*" --tier standard --pages all
mineru config parsing-rules add "*/contracts/*" --tier standard --remote
mineru config parsing-rules list
mineru config parsing-rules remove 3

Use exclude rules to prevent discovery:

bash

mineru config exclude-rules add "*/node_modules/*"
mineru config exclude-rules list
mineru config exclude-rules remove 5

Use

forget

to forget a file or folder from MinerU without deleting source files:

bash

mineru forget "~/Documents/old.pdf"
mineru forget "~/Documents/project"
mineru forget "~/Documents/project" --no-dry-run

Use cleanup for local maintenance:

bash

mineru cleanup deleted-files
mineru cleanup deleted-files --no-dry-run
mineru cleanup orphan-docs
mineru cleanup orphan-docs --no-dry-run
mineru cleanup temp
mineru cleanup temp --older-than 14

Rules:

```
forget
```
does not delete source files.
```
forget
```
does not prevent a watched path from being rediscovered.
If the target is a watch root, remove the watch first. If the target is inside an active watch, warn that a later scan may rediscover it.
```
scan
```
does not create a watch.
```
scan
```
refreshes file discovery state only; it does not mean ingest or parsing has completed.
```
cleanup deleted-files
```
and
```
cleanup orphan-docs
```
default to dry-run; add
```
--no-dry-run
```
only when the user wants actual cleanup.
```
cleanup orphan-docs --no-dry-run
```
can delete cached parsed content for documents no longer linked to any known file path; use it only for maintenance.

Reparse And Cache Control

MinerU caches parse results for the same document and tier.

Force a new parse for the current request:

bash

mineru parse "report.pdf" --force

Invalidate cached parse results:

bash

mineru invalidate "report.pdf"
mineru invalidate "report.pdf" --tier standard

Rules:

Prefer cached results for normal reading.
Use
```
--force
```
when the user asks to reparse or when cached output is known stale or wrong; it skips done cache for this request but does not invalidate or delete old results.
Use
```
invalidate
```
when the user wants future parses and reads to avoid existing done results; invalidation does not automatically start a new parse.
Do not delete user files as part of cache control.

Configuration

Show configuration:

bash

mineru config show
mineru config show --json

Set or unset a value only when the user gives an explicit configuration key:

bash

mineru config get "<key>"
mineru config set "<key>" "<value>"
mineru config unset "<key>"

Important environment variables:

Variable	Meaning
`MINERU_HOME`	MinerU home, default `~/.mineru`
`MINERU_API_KEY`	API key for remote parsing when remote is explicitly allowed

Rules:

Remote URL/API key configuration does not authorize upload by itself.
```
--remote
```
or a remote-enabled parsing rule is still required.
Avoid printing secrets from config.

Remote API Usage

Query usage and limits for the configured Remote API:

bash

mineru usage
mineru usage --json

JSON Output

Use

--json

when an agent needs stable machine-readable fields.

mineru parse --json

returns:

json

{
  "parse": { "...": "parse summary" },
  "content": { "...": "readable content and continuation data" }
}

If parsing is still pending, timed out, or

--no-wait

is used,

content

may be

null

Errors use:

json

{
  "error": {
    "type": "engine_error",
    "code": "quality_tier_unavailable",
    "message": "...",
    "param": "tier",
    "retryable": false,
    "user_action": "...",
    "docs_url": null
  }
}

Agent rules:

Branch on
```
error.code
```
, not on prose in
```
message
```
.
Respect
```
retryable
```
.
Use
```
user_action
```
to decide the next command or user-facing suggestion.
Do not strip locator fields from parsed content; they are needed for continuation and citation.

Error Recovery

Normal-Quality Recovery Gate

When

quality_tier_unavailable

no_engine

is returned for an active document-reading request:

Run
```
mineru server status --json
```
to inspect locally available tiers and parse-server state.
If no local quality tier is available, follow Assess Local Hardware. Do not treat an unconfigured or disabled local parse server as proof that the hardware is unsupported.
Present the currently available tiers. If hardware was assessed, also present the detected hardware and each applicable local tier's hardware status. Then follow the tier-choice guidance in the Quality Tiers section.
Stop and wait for the user to choose a recovery path.
Run only the selected path. If that path fails, report the failure and return to this decision gate with the remaining applicable choices.

Do not use another document parser before this gate unless the user already requested or authorized that fallback. A recoverable MinerU setup or tier error does not by itself mean that MinerU is unavailable.

Use this table for common error codes:

Code	Meaning	Agent action
`server_not_running`	MinerU background service is unavailable	Run `mineru server start` , then retry once
`quality_tier_unavailable`	Normal reading quality is unavailable	Follow the Normal-Quality Recovery Gate; do not fall back automatically
`no_engine`	Requested tier is unavailable locally	Follow the Normal-Quality Recovery Gate; do not fall back automatically
`engine_unavailable`	Engine process unavailable	Retry if `retryable` ; otherwise check `mineru server status`
`parse_server_unavailable`	Parsing service cannot be reached	Check `mineru server status` ; do not switch privacy boundary
`tier_mismatch`	Requested tier unsupported	Ask user to choose a supported tier
`parse_failed`	MinerU could not parse the file	Report failure; suggest a different tier only if privacy rules allow
`parse_timeout`	Parse exceeded timeout	Retry with longer `--wait` , inspect status, or use lower tier if user accepts
`parse_oom`	Memory or VRAM exhausted	Suggest lower quality, smaller `--pages` , or remote only with permission
`remote_not_allowed`	Remote might be needed but was not authorized	Ask user whether uploading is acceptable; do not add `--remote` yourself
`invalid_api_key`	API key invalid	Ask user to set a valid key
`quota_exceeded`	Remote quota exhausted	Suggest waiting or using local
`rate_limit_exceeded`	Remote rate limit	Retry later if appropriate
`file_not_found`	Path or file id missing	Ask for correct path or run `mineru find`
`file_permission_denied`	Local file unreadable	Ask user to fix permissions
`file_type_unsupported`	Format unsupported	Report unsupported type
`file_encrypted`	Password-protected file	Ask user for an unlocked copy
`file_corrupted`	File cannot be read	Ask for a valid copy
`page_range_invalid`	Bad PDF `--pages` value, or `--pages` used with any non-PDF input	Correct the PDF range or omit it for full-document parsing
`parse_not_required`	The input is a directly readable text file	Read the source file directly; do not retry `mineru parse`
`not_cached` / `cache_miss`	Requested cached content does not exist	Run `mineru parse`

Retry rules:

Retry once for transient server startup or explicitly retryable errors.
Do not retry parse failures indefinitely.
Do not change tier, pages, or remote/local privacy boundary without a reason.
Do not add
```
--remote
```
during recovery without user permission.

Answering Users With MinerU Output

When answering after reading a document:

Use the parsed content, not assumptions about the document.
Cite locators when the user needs traceability.
Prefer concise quotations and page/block references over large copied passages.
If content was truncated, say that the answer is based on the pages/blocks read so far.
Continue reading before making claims that require unread sections.
For tables, formulas, figures, or layout-sensitive questions, read the relevant page/block and use image output if needed.

Citation style examples:

text

The warranty period is 24 months (doc:ab12cd3/tier:standard/page:7/block:3).

text

The method is described across pages 4-5; I checked doc:ab12cd3/tier:standard/page:4 and doc:ab12cd3/tier:standard/page:5.

Operating Rules

Do not use
```
flash
```
as default final reading quality.
Do not reparse when a valid locator and cached result are enough.
Do not ignore continuation commands.
Do not load a whole long document when page/block continuation can answer the question.
Do not delete source files.
Do not expose secrets, API keys, or unnecessary local paths.
Do not branch on human prose when JSON
```
error.code
```
or
```
next_request
```
is available.

mineru

NPX Install

Tags

SKILL.md Content

MinerU

When To Use MinerU

Supported Inputs

Do Not

Agent Contract

Core Decision Tree

Common Workflows

First read from a file

Continue progressively

Read or inspect a known location

Search local library, then read

Installation And Setup

Upgrade An Existing Installation

Install with uv (preferred)

Install with pipx

Install with global pip

If No Supported Installer Is Available

After Installation

Privacy Rules

Telemetry

Quality Tiers

Model Engines with Extras

Server Rules

Local Parse Server

Inspect Local Hardware

Choose Extra

Choose Local Tier

Recommend and Ask

Configure Managed Parse Server

First Read From A File

Continue Reading

Read By Locator

Read Page Or Block Images

Search And Find

Inspect Status

Watch, Scan, And Local Library Maintenance

Reparse And Cache Control

Configuration

Remote API Usage

JSON Output

Error Recovery

Normal-Quality Recovery Gate

Answering Users With MinerU Output

Operating Rules

Install with
`uv`
(preferred)

Install with
`pipx`

Install with global
`pip`