How to Configure MinerU for GPU, NPU, or CPU Environments

MinerU automatically detects available accelerators (CUDA, NPU, MPS) and falls back to CPU, but you can explicitly control device selection via the --device CLI flag or the MINERU_DEVICE_MODE environment variable.

Configuring hardware acceleration in MinerU (opendatalab/MinerU) ensures optimal PDF parsing performance across diverse compute environments. Whether deploying on NVIDIA GPUs, Ascend NPUs, Apple Silicon, or CPU-only servers, understanding how to configure MinerU for GPU, NPU, or CPU environments prevents runtime errors and maximizes throughput. The configuration system probes for available hardware and manages memory allocation automatically, while still allowing granular control through command-line arguments or environment variables.

Device Selection Methods

MinerU offers three mechanisms to specify the compute device, implemented in mineru/cli/client.py and mineru/utils/config_reader.py.

CLI --device Flag

The most direct method uses the command-line interface. In mineru/cli/client.py (lines 128-134), the --device argument accepts specific device strings to force a particular execution target:

• cpu – Force CPU-only execution
• cuda or cuda:0 – Use the first NVIDIA GPU (or specify by index)
• npu or npu:0 – Use the first Ascend NPU (or specify by index)
• mps – Use Apple Silicon Metal Performance Shaders

mineru -p ./document.pdf -o ./output --device cuda:0

Environment Variable MINERU_DEVICE_MODE

For persistent configuration across sessions or container deployments, set the MINERU_DEVICE_MODE environment variable. This variable is read by get_device() in mineru/utils/config_reader.py (lines 75-82) when no CLI flag is provided.

export MINERU_DEVICE_MODE=npu
export MINERU_VIRTUAL_VRAM_SIZE=12
mineru -p ./document.pdf -o ./output

Automatic Device Detection

When no explicit configuration is provided, MinerU probes the system sequentially: CUDA → MPS → NPU → other accelerators (gcu, musa, mlu, sdaa) → CPU. The get_device() function implements this fallback chain, ensuring the library runs on any hardware without manual intervention.

Prerequisites and Installation

Before configuring hardware acceleration, install the full dependency stack to ensure accelerator binaries are available:

pip install uv
uv pip install -U "mineru[all]"

The [all] extra pulls in torch, torchvision, torch_npu, and onnxruntime-gpu, enabling support for all device types.

Verify that PyTorch can detect your hardware:

python -c "import torch; print('CUDA:', torch.cuda.is_available())"
python -c "import torch_npu; print('NPU:', torch_npu.npu.is_available())"

Step-by-Step Configuration Guide

1. Verify Hardware Availability

Run the verification commands above to confirm your accelerator is visible to the Python runtime. If these return False, check your driver installation (NVIDIA CUDA toolkit or CANN toolkit for NPUs) before proceeding.

2. Select the Compute Device

Choose one of the following approaches based on your deployment scenario:

• One-off executions: Use --device <target> (e.g., --device cuda, --device npu:0, --device cpu)
• Persistent sessions: Export MINERU_DEVICE_MODE=<target> in your shell profile or Docker environment
• Development/testing: Omit both to let MinerU auto-select the best available device

3. Choose the Appropriate Backend

The device selection must align with the processing backend. GPU and NPU acceleration are only available for specific engines:

• GPU/NPU local acceleration: Use hybrid-auto-engine (default) or vlm-auto-engine
• CPU-only or low-VRAM machines: Use pipeline backend
• Remote inference servers: Use *-http-client backends (e.g., hybrid-http-client), which require no local acceleration

# CPU-only example

mineru -p ./doc.pdf -o ./out -b pipeline --device cpu

4. Configure VRAM Limits (Optional)

For large models or shared GPU environments, limit per-process memory consumption using the --vram flag (in gigabytes) or the MINERU_VIRTUAL_VRAM_SIZE environment variable. The default value is the total memory of the selected device as queried by get_vram() in mineru/utils/model_utils.py.

mineru -p ./doc.pdf -o ./out --device cuda --vram 8

How Device Configuration Works Under the Hood

Device Resolution Logic

In mineru/cli/client.py, the get_device_mode() helper merges CLI arguments with environment state. It prioritizes the --device flag; if absent, it calls get_device() from mineru/utils/config_reader.py, which checks MINERU_DEVICE_MODE before falling back to automatic hardware probing.

VRAM Calculation

The get_vram() function in mineru/utils/model_utils.py (lines 450-466) queries the selected device using PyTorch APIs (torch.cuda.get_device_properties, torch_npu.npu.get_device_properties, etc.) and converts bytes to gigabytes. When the --vram flag is set, get_virtual_vram_size() in client.py overrides the detected value.

Backend Initialization

Once resolved, the selected device string is stored in os.environ["MINERU_DEVICE_MODE"]. All subsequent model loaders in mineru/model/ and mineru/backend/ read this variable to move tensors to the correct device and import appropriate acceleration libraries (e.g., onnxruntime-gpu, torch_npu).

Practical Configuration Examples

GPU (CUDA) Acceleration

Run on the first available GPU using the default hybrid engine:

mineru -p ./docs/physics.pdf -o ./out --device cuda

NPU (CANN) Acceleration

Explicitly bind to a specific NPU card using environment variables:

export MINERU_DEVICE_MODE=npu:0
mineru -p ./docs/chinese.pdf -o ./out

CPU-Only Execution

Force CPU processing with the pipeline backend:

mineru -p ./docs/manual.pdf -o ./out -b pipeline --device cpu

Docker Deployment

Force CPU mode and disable VRAM allocation in a container:

docker run --rm -e MINERU_DEVICE_MODE=cpu \
           -e MINERU_VIRTUAL_VRAM_SIZE=0 \
           opendatalab/mineru:latest \
           mineru -p /data/input.pdf -o /data/out -b pipeline

Programmatic Python Usage

Configure devices when calling MinerU from Python scripts:

import os
os.environ["MINERU_DEVICE_MODE"] = "cuda"
os.environ["MINERU_VIRTUAL_VRAM_SIZE"] = "10"  # 10 GB cap

from mineru.cli.client import main as mineru_cli

mineru_cli(
    None,
    input_path="sample.pdf",
    output_dir="result",
    method="auto",
    backend="hybrid-auto-engine",
    lang="en",
    server_url=None,
    start_page_id=0,
    end_page_id=None,
    formula_enable=True,
    table_enable=True,
    device_mode=None,  # Let env-var take precedence

    virtual_vram=None,
    model_source="huggingface"
)

Summary

• MinerU supports CPU, CUDA (NVIDIA), NPU (Ascend CANN), and MPS (Apple Silicon) through a unified configuration interface.
• Use the --device CLI flag for one-off executions or MINERU_DEVICE_MODE for persistent environment configuration.
• GPU and NPU acceleration require the hybrid-auto-engine or vlm-auto-engine backends; CPU-only deployments must use the pipeline backend.
• Control memory usage with --vram or MINERU_VIRTUAL_VRAM_SIZE to prevent out-of-memory errors on shared hardware.
• The device selection logic resides in mineru/utils/config_reader.py, while VRAM calculations are handled in mineru/utils/model_utils.py.

Frequently Asked Questions

What is the default device if I don't specify one?

MinerU automatically probes for CUDA, then MPS (Apple Silicon), then NPU (CANN), then other vendor-specific accelerators (gcu, musa, mlu, sdaa), and finally falls back to CPU. This logic is implemented in the get_device() function in mineru/utils/config_reader.py.

Can I use GPU acceleration with any backend?

No. GPU and NPU acceleration are only available when using the hybrid-auto-engine or vlm-auto-engine backends. If you are running on CPU-only hardware or want to avoid loading CUDA/NPU libraries, you must use the pipeline backend or a remote *-http-client backend.

How do I limit GPU memory usage in MinerU?

Use the --vram CLI flag followed by the desired gigabytes (e.g., --vram 8 for 8GB) or set the MINERU_VIRTUAL_VRAM_SIZE environment variable. The get_vram() function in mineru/utils/model_utils.py enforces this limit by returning the minimum of the detected device memory and your specified cap.

Does MinerU support multi-GPU setups?

Yes. Specify the device index using colon syntax: --device cuda:0 for the first GPU, --device cuda:1 for the second, or --device npu:0 for the first Ascend NPU. This binding ensures the process uses only the specified accelerator card.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}