Guide · Open source
How to use Unlimited-OCR: install, run and parse multi-page documents
Updated · written with AI from the project's own documentation and checked against our catalogue data
Unlimited-OCR is an open-source document-parsing model from Baidu that reads page images and converts them into structured text. This guide is for developers and engineers who want to run it locally on an NVIDIA GPU. By the end you will know the prerequisites, how to install the Transformers and SGLang setups, and how to parse single and multi-page documents.
Unlimited OCRbaidu/Unlimited-OCR · ★ 30.3k · MIT Install options & downloads Quick start
- 1Check prerequisites. Confirm Python 3.10, an NVIDIA GPU with CUDA, and uv if you plan to use SGLang.
- 2Install Transformers dependencies. Run the pinned pip install command from the README.
- 3Load the model. Load baidu/Unlimited-OCR-2 with trust_remote_code and move it to the GPU.
- 4Parse a single page. Call model.infer with one page image and an output path.
- 5Parse a multi-page document. Pass all page images in order to model.infer_multi.
- 6Set up SGLang. Create the uv virtualenv, install the SGLang wheel and PyMuPDF, then set the environment variables from the README.
- 7Start the server. Run the sglang.launch_server command and confirm it listens on port 10000.
What you need before you install Unlimited-OCR
The README lists Python 3.10, an NVIDIA GPU with CUDA, and uv for the SGLang setup. The tested configuration in the README is an NVIDIA A800-80GB, and the examples assume CUDA hardware, so a CPU-only machine is not covered by the source.
The model is hosted on Hugging Face as baidu/Unlimited-OCR-2. Your input must be page images, so PDFs need to be converted first; the SGLang section uses PyMuPDF for that.
- Python 3.10
- NVIDIA GPU with CUDA
- uv (required for the SGLang setup)
Install the Transformers dependencies with pip
For the native Transformers route, install the pinned packages from the README. The versions below are the ones the README says it was tested with, so use them as written.
pip install torch==2.13.0 torchvision pillow transformers==4.52.1 huggingface-hub==0.36.0 \
tokenizers==0.21.4 addict==2.4.0 einops==0.8.2 easydict==1.13Parse a single page with infer
Load the tokenizer and model once with trust_remote_code, then call infer on one image. The README says a single page is encoded with dynamic tiling (gundam mode) by default. Results are written to the output path when save_results is set.
- The model is loaded in bfloat16 and moved to the GPU with .cuda().
- Replace your_doc/page_1.jpg with the path to your own page image.
import torch
from transformers import AutoModel, AutoTokenizer
model_name = "baidu/Unlimited-OCR-2"
tokenizer = AutoTokenizer.from_pretrained(model_name, trust_remote_code=True)
model = AutoModel.from_pretrained(model_name, trust_remote_code=True, use_safetensors=True,
torch_dtype=torch.bfloat16).eval().cuda()
text = model.infer(tokenizer, image_file="your_doc/page_1.jpg",
output_path="output/single", save_results=True)Parse a multi-page document with infer_multi
Use infer_multi when pages belong to one document, because the model can use context across pages. Pass the page images in page order. The README says the prompt is built automatically and each page is encoded as one global view (base mode), and the output contains one <PAGE> marker per input page in the same order as your image list.
- Keep image_files in page order, since the output follows that order.
- infer_multi returns the text and a token count.
pages = [f"your_doc/page_{i}.jpg" for i in range(1, 8)]
text, num_tokens = model.infer_multi(tokenizer, image_files=pages,
output_path="output/multi", save_results=True)Set up and start the SGLang server
The README recommends SGLang for serving. Create a uv virtualenv, install the customized SGLang wheel that the README names, then install PyMuPDF for PDF-to-image conversion. The README also lists an extra package, fastokens, used by the launch command.
Before launching, the README sets several environment variables that control page-window scheduling and memory use for long documents. Read the comments in the README for each value, because they change memory behaviour.
- SGLANG_UOCR_EANABLE_DOC_LIMIT sets page-window scheduling: 1 enables it, 0 processes the whole document in one window.
- SGLANG_UOCR_DOC_GUNDAM_PAGE_WINDOW and SGLANG_UOCR_DOC_BASE_PAGE_WINDOW set pages per window; the README uses 10 for both.
- SGLANG_UOCR_MAX_PAGE_TOKENS caps output per page and must be greater than 0.
- The README notes that the default SAM chunk cap of 512 can cause an out-of-memory error, and that 64 is equivalent with a lower peak.
uv venv --python 3.10
source .venv/bin/activate
uv pip install wheel/sglang-0.5.20.dev13+g75b9b06b02-py3-none-any.whl
uv pip install pymupdf==1.27.2.2
uv pip install fastokens==0.3.2Launch the server and check it runs
Start the server with the command from the README. It listens on port 10000 and serves the model under the name Unlimited-OCR-2. The README's launch command includes many tuning flags, such as memory fraction and CUDA graph settings; the source describes them as tuned for its setup, so change them only with a reason.
Note that the README's environment variable is spelled SGLANG_UOCR_EANABLE_DOC_LIMIT in the source; use the exact name shown.
- The server binds to 0.0.0.0 on port 10000 in the README example.
- The README shows --mem-fraction-static 0.7 and --max-running-requests 64.
python -m sglang.launch_server \
--model-path baidu/Unlimited-OCR-2 \
--served-model-name Unlimited-OCR-2 \
--chat-template unlimited-ocr \
--tokenizer-backend fastokens \
--tokenizer-worker-num 8 \
--mem-fraction-static 0.7 \
--max-running-requests 64 \
--max-prefill-tokens 2048 \
--enable-custom-logit-processor \
--enable-streaming-session \
--allow-auto-truncate \
--disable-radix-cache \
--mm-preprocess-cache-size-mb 0 \
--cuda-graph-backend-decode full --cuda-graph-max-bs-decode 64 \
--cuda-graph-backend-prefill full \
--cuda-graph-max-bs-prefill 16384 \
--cuda-graph-bs-prefill 1024 2048 \
--cuda-graph-config '{"prefill": {"backend": "full", "full_prefill_max_req": 64}}' \
--host 0.0.0.0 \
--port 10000Choose between Transformers and SGLang
The README describes Transformers as native and suited to quick tests, and SGLang as recommended for serving. The source does not give client code for calling the SGLang server, so check the README or SGLang documentation for how to send requests.
- Transformers: quick tests and single runs from Python.
- SGLang: serving, with page-window scheduling for long documents.
What people use it for
- Parsing multi-page scanned documents with a locally hosted model.
- Processing long PDFs after converting each page to an image.
- Comparing long-document OCR models using the MarathonDocBench benchmark.
- Running a GPU-backed SGLang server for document parsing.
Frequently asked questions
Is Unlimited-OCR free to use?
The repository is released under the MIT license, as stated in the source. The README does not describe pricing for the Hugging Face model or other hosts, so check the license file in the repository for the terms.
What hardware do I need to run Unlimited-OCR?
The README lists Python 3.10 and an NVIDIA GPU with CUDA. Its tested setup is an NVIDIA A800-80GB, and the examples assume CUDA hardware. The source does not give minimum GPU memory.
How do I parse a multi-page PDF with Unlimited-OCR?
The model takes page images, so convert each PDF page to an image first; the README's SGLang setup installs PyMuPDF for this. Then pass the images in page order to model.infer_multi.
What is the difference between infer and infer_multi?
infer parses a single page and uses dynamic tiling (gundam mode) by default. infer_multi parses all pages of a document in one request so the model can use cross-page context, encoding each page as a base-mode global view.
Why does my SGLang server run out of memory?
The README warns that the default SAM chunk cap of 512 allows a single large allocation and can cause an out-of-memory error. It suggests setting SGLANG_OPT_UOCR_SAM_REL_POS_BIAS_MB=64, which it says is equivalent with a lower peak.
How does Unlimited-OCR compare with DeepSeek-OCR, PaddleOCR and Tesseract?
The README says Unlimited-OCR aims to push DeepSeek-OCR one step further and claims state-of-the-art results on long-document benchmarks. The source does not include a head-to-head comparison with PaddleOCR or Tesseract, so test on your own documents before choosing.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Unlimited-OCR suits developers and teams with an NVIDIA GPU who want a locally hosted model for multi-page document parsing. It is less suitable if you need a point-and-click tool, lack CUDA hardware, or need proven accuracy on your own documents, since the README's benchmark claims are not independently verified here.
Install options & downloads