---
id: mineru-vl-utils
version: "1.2.1"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# mineru-vl-utils — Utilities for MinerU Vision-Language models

License: permissive · Maintenance: active · Downloads: 198.5K/mo

## What it is and what it does

mineru-vl-utils is a client library for the MinerU Vision-Language Model, a multimodal AI system that detects document layout and recognizes text, tables, equations, and images from visual input. It abstracts away the complexity of model serving and inference by providing a unified MinerUClient interface that works across seven different deployment modes: http-client (remote server), transformers (HuggingFace), mlx-engine (Apple Silicon), lmdeploy-engine, vllm-engine (synchronous), vllm-async-engine (asynchronous), and llama-cpp-engine (in-process). The model outputs structured ContentBlock objects containing block type, bounding box, rotation angle, and recognized content (text as strings, tables as HTML, equations as LaTeX).

You use it by instantiating a MinerUClient with your chosen backend, then calling two_step_extract() on images to get back a list of detected and recognized content blocks. The package handles all the marshalling between your code and the underlying model, whether that model runs locally via transformers, on Apple Silicon via mlx-engine, in a remote HTTP service, or in-process via llama-cpp-engine. Installation is modular: the base package includes http-client support, and optional extras pull in backend-specific dependencies.

Use it for:

- Extract structured text, tables, and equations from scanned documents or PDFs for downstream processing.
- Detect and localize text regions in document images for document layout analysis.
- Convert document images to structured HTML or LaTeX for archival or republishing workflows.
- Run document understanding on Apple Silicon Macs without external servers using the mlx-engine backend.
- Build a document processing service using the http-client backend to call a centralized model server.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Provides a lightweight Python wrapper to interact with the MinerU Vision-Language Model, supporting multiple deployment backends for document layout detection and content recognition.

Yes. The package is actively maintained (released one day ago), has low install friction, carries a permissive Apache-2.0 license, and offers a clean abstraction over a capable multimodal model with flexible deployment options. Choose it if you need to extract structured content from documents and want to avoid managing model serving yourself; the http-client backend requires an external server, but other backends let you run inference locally.

## Install

pip install mineru-vl-utils
uv add mineru-vl-utils
poetry add mineru-vl-utils

## Installing mineru-vl-utils

Before you install: Low friction: pure Python wheel with seven common runtime dependencies. Actively maintained with a release one day ago. Requires Python 3.10 or later.

License in practice: Apache-2.0 permissive license allows commercial and private use with minimal restrictions, making it safe for most projects.

Quickstart:

pip install mineru-vl-utils

from mineru_vl_utils import MinerUClient

client = MinerUClient(backend="http-client", server_url="http://127.0.0.1:8000")
extracted_blocks = client.two_step_extract(image)

For http-client backend, you must have a separate vllm or LLM deployment tool serving the MinerU model as an HTTP server on the specified URL.

Verify before relying:

- Whether the package supports async operations across all seven backends or only specific ones.
- Performance characteristics and latency expectations for each backend type.
- Whether the http-client backend requires network connectivity or can work offline once the model is cached.
- Specific model size and memory requirements for each backend deployment mode.

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 198.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

vision language model wrapper, document layout detection, table and equation recognition, mineru vl client, multimodal document extraction, vllm transformers mlx backend, text table equation detection, document-extraction, vision-language-model, multimodal-inference

[View on SkillFed](https://skillfed.io/packages/mineru-vl-utils) · [View on PyPI](https://pypi.org/project/mineru-vl-utils/)