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

> Learn to configure MinerU for GPU, NPU, or CPU on macOS, Windows, or Linux. Control device selection with CLI flags or environment variables for optimal performance.

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

---

**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`](https://github.com/opendatalab/MinerU/blob/main/mineru/cli/client.py) and [`mineru/utils/config_reader.py`](https://github.com/opendatalab/MinerU/blob/main/mineru/utils/config_reader.py).

### CLI `--device` Flag

The most direct method uses the command-line interface. In [`mineru/cli/client.py`](https://github.com/opendatalab/MinerU/blob/main/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

```bash
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`](https://github.com/opendatalab/MinerU/blob/main/mineru/utils/config_reader.py) (lines 75-82) when no CLI flag is provided.

```bash
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:

```bash
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:

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

```bash

# 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`](https://github.com/opendatalab/MinerU/blob/main/mineru/utils/model_utils.py).

```bash
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`](https://github.com/opendatalab/MinerU/blob/main/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`](https://github.com/opendatalab/MinerU/blob/main/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`](https://github.com/opendatalab/MinerU/blob/main/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`](https://github.com/opendatalab/MinerU/blob/main/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:

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

```

### NPU (CANN) Acceleration

Explicitly bind to a specific NPU card using environment variables:

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

```

### CPU-Only Execution

Force CPU processing with the pipeline backend:

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

```

### Docker Deployment

Force CPU mode and disable VRAM allocation in a container:

```bash
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:

```python
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`](https://github.com/opendatalab/MinerU/blob/main/mineru/utils/config_reader.py)**, while VRAM calculations are handled in **[`mineru/utils/model_utils.py`](https://github.com/opendatalab/MinerU/blob/main/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`](https://github.com/opendatalab/MinerU/blob/main/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`](https://github.com/opendatalab/MinerU/blob/main/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.