System Requirements for Running MinerU: Hardware, Software, and GPU Configuration

MinerU requires Python 3.10–3.13, runs on Linux/Windows/macOS with 16 GB RAM minimum (32 GB recommended), and supports optional GPU acceleration requiring 6–10 GB VRAM depending on the backend.

MinerU is a cross-platform document-parsing engine developed by OpenDataLab that processes PDFs using either pure-CPU mode or hardware acceleration. Understanding the system requirements for running MinerU ensures optimal performance whether you are deploying on a local workstation, a GPU server, or Apple Silicon. The repository provides detailed specifications in the README and runtime detection utilities to validate your environment before execution.

Operating System and Python Version Requirements

MinerU supports Linux, Windows, and macOS with specific version constraints documented in README.md. Linux kernels from 2019 onwards are fully supported, Windows 10 and newer are compatible, and macOS requires version 14.0 or later for Apple Silicon systems.

The project declares Python version support in pyproject.toml (lines 14–17), specifically supporting Python 3.10 through 3.13. However, Windows users should note a critical limitation: due to the ray dependency not yet supporting Python 3.13, Windows installations are currently restricted to Python 3.10–3.12 only, as documented in the system requirements table at lines 70–72.

Hardware Requirements: CPU, RAM, and Storage

CPU and Architecture

MinerU operates on any modern x86_64 or ARM CPU architecture. The pure-CPU backend, referred to as pipeline, functions across all supported platforms without specialized hardware. For GPU acceleration, NVIDIA Volta architecture or newer (e.g., RTX 20-series and above) is required.

Memory and Disk Space

The minimum RAM requirement is 16 GB, though 32 GB or more is recommended for heavy document processing workloads. Storage requirements vary by deployment mode: the standard installation requires 20 GB of SSD space, while the lightweight client mode requires only 2 GB.

GPU and Accelerator Support

NVIDIA CUDA Requirements

GPU-accelerated backends demand specific VRAM allocations based on the processing mode. According to the README (lines 85–89):

• Pipeline backend: 6 GB VRAM minimum
• Auto-engine backend: 10 GB VRAM minimum
• VLM (Vision Language Model): 8 GB VRAM
• HTTP client mode: 3 GB VRAM

Apple Silicon Support

For Apple Silicon Macs, MinerU requires macOS 13.5 or later, though the README specifies macOS 14.0+ for full compatibility. The runtime validation occurs through the is_mac_os_version_supported function in mineru/utils/check_sys_env.py (lines 25–33), which accepts a minimum version parameter defaulting to "13.5".

Other Accelerators (NPU, MUSA)

Beyond NVIDIA and Apple Silicon, MinerU supports various acceleration cards including Ascend (CANN), Tecorigin (MUSA), and other NPU hardware through dedicated documentation sections referenced in the README (lines 48–60).

Runtime Environment Detection

The repository includes a utility module at mineru/utils/check_sys_env.py that programmatically detects the current operating environment. This module provides functions such as is_windows_environment(), is_mac_environment(), is_linux_environment(), is_apple_silicon_cpu(), and is_mac_os_version_supported() to enable adaptive code execution.

Guarding GPU-Only Features

Use the detection utilities to conditionally enable CUDA-dependent features:

from mineru.utils.check_sys_env import (
    is_linux_environment,
    is_windows_environment,
    is_mac_os_version_supported,
)

def gpu_supported() -> bool:
    # MinerU needs a CUDA-compatible GPU on Linux/Windows.

    # macOS uses Apple-Silicon acceleration, not CUDA.

    return (is_linux_environment() or is_windows_environment()) and not is_mac_os_version_supported()

if gpu_supported():
    print("GPU acceleration is available – you can enable the 'auto-engine' backend.")
else:
    print("Running in CPU-only mode (backend='pipeline').")

Selecting the Optimal Backend at Startup

Dynamically choose processing backends based on hardware capabilities:

import mineru.cli.client as client
from mineru.utils.check_sys_env import (
    is_mac_environment,
    is_apple_silicon_cpu,
    is_mac_os_version_supported,
)

def choose_backend() -> str:
    # Prefer hybrid-auto-engine when hardware permits.

    if is_mac_environment() and is_apple_silicon_cpu() and is_mac_os_version_supported():
        return "hybrid-auto-engine"
    elif client.check_gpu_available():
        return "vlm-auto-engine"
    else:
        return "pipeline"  # pure-CPU fallback

backend = choose_backend()
print(f"Selected backend: {backend}")

Verifying Environment Before Batch Jobs

Validate system compatibility programmatically using a bash wrapper:

#!/usr/bin/env bash
python - <<'PY'
from mineru.utils.check_sys_env import (
    is_linux_environment,
    is_windows_environment,
    is_mac_environment,
    is_apple_silicon_cpu,
    is_mac_os_version_supported,
)

assert is_linux_environment() or is_windows_environment() or is_mac_environment(), \
    "Unsupported OS – MinerU runs on Linux, Windows, or macOS only."

if is_mac_environment():
    assert is_apple_silicon_cpu() and is_mac_os_version_supported(), \
        "macOS must be Apple-Silicon and version ≥13.5."
print("Environment check passed.")
PY

Summary

• MinerU supports Linux (kernel ≥2019), Windows 10+, and macOS 14.0+ (Apple Silicon) with Python 3.10–3.13 (Windows limited to 3.10–3.12 due to ray compatibility).
• Minimum hardware requirements include 16 GB RAM (32 GB recommended) and 20 GB SSD storage (2 GB for client mode).
• GPU acceleration requires NVIDIA Volta+ with 6 GB VRAM for pipeline mode or 10 GB for auto-engine mode; Apple Silicon requires macOS ≥13.5.
• Use the mineru/utils/check_sys_env.py utilities to programmatically validate system compatibility before deployment.

Frequently Asked Questions

Does MinerU support Python 3.13?

Yes, MinerU supports Python 3.10 through 3.13 as declared in pyproject.toml. However, Windows users are currently restricted to Python 3.10–3.12 because the ray dependency does not yet support Python 3.13 on Windows platforms.

How much VRAM do I need for GPU acceleration?

VRAM requirements depend on your selected backend. The pipeline backend requires 6 GB, the auto-engine backend requires 10 GB, VLM processing requires 8 GB, and the HTTP client mode requires 3 GB. These specifications are documented in the README.md system requirements table at lines 85–89.

Can I run MinerU on Windows with Python 3.13?

No, Windows users cannot currently use Python 3.13 with MinerU due to compatibility issues with the ray library. You must use Python 3.10, 3.11, or 3.12 on Windows systems until upstream support is added.

How do I check if my Mac supports Apple Silicon acceleration?

Import is_apple_silicon_cpu and is_mac_os_version_supported from mineru/utils/check_sys_env.py. The latter function defaults to checking for macOS 13.5 or later. For optimal compatibility, ensure you are running macOS 14.0 or newer on an M1, M2, or later Apple Silicon processor.

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