MinerU PDF to Markdown Converter

Common errors

• failed to read file, please check if the file is corrupted and try uploading again

  cause The MinerU API backend could not access, download, or correctly parse the provided file, often due to an inaccessible URL, an invalid PDF, or attempting to pass a URL when the API expects multipart file content.
  fix Ensure the file URL is publicly accessible and points directly to a valid PDF. If using an API, ensure you are uploading the *file content* via `multipart/form-data` to the `/file_parse` endpoint, not just the URL or metadata. Verify your MinerU environment is up to date with all required models.

• {'error': {'message': 'Either text, input_ids or input_embeds should be provided. '}}

  cause This error occurs when an API request to a text/image prompt endpoint (like `/generate`) is made without providing the required input fields, but is often seen when mistakenly sending a PDF extraction request to this endpoint instead of the dedicated PDF parsing endpoint.
  fix For PDF extraction, ensure you are sending requests to the correct endpoint, typically `/file_parse` or `/tasks` for asynchronous processing, and that you are providing the actual PDF file content as `multipart/form-data`.

• Error: 1 task(s) failed while processing documents: task#1 (your_document.pdf): Timed out while polling task status for task

  cause Tasks stuck in 'processing' or timing out, especially with `vllm-async-engine`, can be due to missing environment variables, GPU memory issues, or CPU inference timeouts for large documents.
  fix If using `vllm-async-engine`, ensure `VLLM_USE_V1=1` is explicitly set as an environment variable. If on CPU, increase the timeout with `MINERU_PDF_RENDER_TIMEOUT=600` (for 600 seconds). For GPU issues, monitor memory usage and try switching to the `pipeline` backend (`-b pipeline`) for basic CPU processing.

Warnings

• breaking Version 2.0 and later removed the `pymupdf` dependency. Code relying on direct `pymupdf` calls or specific behaviors might break.
  Fix: Review your code for `pymupdf` interactions and adapt to MinerU's native parsing or updated API. Ensure a clean installation to avoid dependency conflicts.
• gotcha Python 3.13 has limited support on Windows due to underlying dependencies like `ray`. Users on Windows should stick to Python 3.10, 3.11, or 3.12.
  Fix: Use a Python environment with version 3.10, 3.11, or 3.12 on Windows. Consider Linux or macOS for Python 3.13+ environments if `ray` is a critical dependency.
• gotcha Parsing complex documents may result in inaccurate output for specific elements. Known limitations include reading order in extremely complex layouts, limited vertical text support, recognition issues with uncommon list formats, lack of code block recognition, poor parsing of comic books/art albums/primary school textbooks, table recognition errors in complex tables, and inaccurate OCR for lesser-known languages.
  Fix: For critical documents with these characteristics, manually review and correct outputs. Consider submitting issues with example files to the MinerU GitHub repository for ongoing improvements. Use `--log-level debug` to gain more insight into parsing steps.
• gotcha When parsing multiple PDFs in a loop, especially with the `vllm` backend, users might encounter `PdfiumError ("Failed to import pages")` due to resource exhaustion or `PDFium`'s non-thread-safe nature.
  Fix: Manually clear GPU memory (`torch.cuda.empty_cache()`, `gc.collect()`), reduce batch size, split large PDFs, or consider the `pipeline` backend for robustness. Upgrade `mineru` and `pypdfium2` to the latest versions for potential stability fixes.

Install

• pip install -U "mineru[all]" Recommended for full features
• pip install "mineru[core]" Basic installation

Imports

• parse_doc
  wrong:

  from mineru import parse_doc

  correct:

  from mineru.utils.demo_utils import parse_doc

  The primary parsing function, `parse_doc`, is often found within `mineru.utils.demo_utils` in examples, rather than directly under the top-level `mineru` package. While direct API access might exist, demo utilities are frequently used for quickstarts.

Quickstart

This quickstart demonstrates how to use MinerU's Python API to convert a local PDF file into Markdown format. It creates an output directory and uses the `parse_doc` function from `mineru.utils.demo_utils`. Users should replace `your_document.pdf` with the actual path to their PDF file. The `backend` parameter can be adjusted for CPU-only (pipeline) or GPU-accelerated (e.g., vlm-transformers) inference.

import os
from pathlib import Path
from mineru.utils.demo_utils import parse_doc

# Create a dummy PDF file for demonstration
# In a real scenario, replace 'input.pdf' with your actual PDF file path.
# This example assumes you have a 'demo_pdfs' directory with 'demo1.pdf'
# or create a placeholder for testing purposes.

# Example placeholder for an input PDF file
# For a real run, ensure 'your_document.pdf' exists or create it.
input_pdf_path = Path("your_document.pdf") # Replace with a real PDF path
if not input_pdf_path.exists():
    print(f"Warning: '{input_pdf_path}' not found. Please provide a valid PDF for the quickstart.")
    # Create a dummy file for execution to pass
    with open(input_pdf_path, 'w') as f:
        f.write("This is a dummy PDF content for testing.")
    print(f"Created a dummy '{input_pdf_path}' for demonstration. Parsing might not yield meaningful results.")

output_directory = Path("mineru_output")
output_directory.mkdir(exist_ok=True)

print(f"Parsing {input_pdf_path} to Markdown...")

# Parse the document using the pipeline backend (CPU-friendly)
# 'lang' can be adjusted, e.g., 'en' for English.
# 'backend' can be 'vlm-transformers' for higher accuracy if GPU is available.
parse_doc(
    path_list=[input_pdf_path],
    output_dir=output_directory,
    lang="en",
    backend="pipeline", # Use 'vlm-transformers' or 'vlm-sglang-engine' if GPU is available
    f_dump_md=True # Output markdown files
)

print(f"Parsing complete. Check output in: {output_directory.resolve()}")

# Clean up the dummy file if it was created
if input_pdf_path.name == "your_document.pdf" and input_pdf_path.exists() and input_pdf_path.stat().st_size < 100:
    input_pdf_path.unlink()