DeepSeek-OCR Setup Guide: Run the Best Open OCR Model Locally

DeepSeek-OCR runs locally in one command: ollama run deepseek-ocr — a 6.7GB download, MIT-licensed, free. It is a 3B mixture-of-experts model (~570M active parameters) that converts documents to clean markdown using as few as 100 vision tokens per page; DeepSeek's own pipeline processes 200K+ pages per day on a single A100-40G. A 12GB GPU runs it comfortably; for folders of PDFs, serve it with vLLM v0.11.1+ instead of Ollama.

That is the whole recommendation. The rest of this guide is the detail: exactly what to install for each of the three official paths, the prompts that unlock document-to-markdown mode (they are not obvious), what the five resolution modes cost in tokens, where the model genuinely fails, and what the January release of DeepSeek-OCR 2 means for which one you should run today.

---

Why DeepSeek-OCR Took Over {#why-it-matters}

DeepSeek-OCR replaced the classic OCR pipeline — detect, crop, recognize, reassemble — with a single vision-language model that reads a page the way an LLM reads text. Released in October 2025 (repo live October 17, paper on arXiv October 21), it sits at 23,743 GitHub stars as of August 5, 2026 (GitHub API), and the Hugging Face weights are one 6.7GB file under MIT.

The reason it dominated every 2026 OCR comparison is not raw accuracy — it is efficiency. The paper (arXiv 2510.18234) frames OCR as "contexts optical compression": squeeze a page of text into a handful of vision tokens, then decode. Its reported numbers:

• ~97% decoding precision at under 10x compression (up to 10 text tokens represented per vision token), falling to ~60% at 20x — the paper's own figures.
• On OmniDocBench, it beats GOT-OCR2.0 (which spends 256 tokens/page) using only 100 vision tokens, and outperforms MinerU2.0 (6,000+ tokens/page) with fewer than 800 — again per the paper.
• Architecture: a ~380M-parameter DeepEncoder (SAM-base at 80M and CLIP-large at 300M in series, with a 16x convolutional compressor between them) feeding a DeepSeek-3B-MoE decoder that activates about 570M parameters per token (6 of 64 routed experts plus 2 shared).

Fewer tokens per page means faster decoding, cheaper batching, and less VRAM burned on context — which is exactly what you want when the job is "OCR this entire filing cabinet" rather than "read this one screenshot."

---

What You Need to Run It {#requirements}

The short version: any modern NVIDIA GPU with 12GB+ VRAM, or just Ollama v0.13.0+ if you'd rather skip the Python environment entirely.

DeepSeek publishes no consumer-GPU minimum — every official figure comes from an A100-40G. Our working estimate from the weight size: 12GB is the sane floor for the BF16 model, 8GB is borderline once the vision encoder and an 8K-token output budget claim their share. There is no official quantized release, and notably Ollama's 6.7GB package is the same size as the BF16 weights — it is not a 4-bit quant, so Ollama does not lower the memory bar the way it does for chat models.

If you're deciding what card clears that bar, our hardware hub maps the current market, and the best LLMs for 8GB VRAM page shows what else lives comfortably in the same footprint.

---

Fastest Path: Ollama {#ollama}

Two commands, no Python, working OCR:

ollama pull deepseek-ocr     # 6.7GB; needs Ollama v0.13.0 or newer
ollama run deepseek-ocr "Convert the document to markdown. ./invoice.png"

Passing images works like every Ollama vision model: include the file path in the prompt and the CLI attaches it — the official library page's own example is exactly that, a path plus an instruction in one string. For scripts, the REST API takes base64-encoded images in an images array:

curl http://localhost:11434/api/generate -d '{
  "model": "deepseek-ocr",
  "prompt": "Convert the document to markdown.",
  "images": ["<base64-encoded page image>"],
  "stream": false
}'

Two things worth knowing before you build on this path. First, the Ollama package runs with an 8K context window — plenty for typical pages, but a dense table-heavy page can push output toward that ceiling (the official repo itself caps generation at 8,192 tokens). Second, PDFs are not a native input anywhere in this stack: convert pages to PNG first (pdftoppm -png file.pdf page or PyMuPDF), then feed the images. If the end goal is searchable archives rather than raw text, our local AI document scanner guide covers that whole pipeline.

---

Batch Path: vLLM {#vllm}

DeepSeek-OCR is supported in upstream vLLM — the official README lists v0.11.1 and newer (the repo's own bundled scripts pin an older 0.8.5 wheel instead), so a plain current install works:

uv venv && source .venv/bin/activate
uv pip install -U vllm --torch-backend auto

For an OpenAI-compatible server, the vLLM recipe's exact command is:

vllm serve deepseek-ai/DeepSeek-OCR \
  --logits_processors vllm.model_executor.models.deepseek_ocr:NGramPerReqLogitsProcessor \
  --no-enable-prefix-caching \
  --mm-processor-cache-gb 0

Those flags are not optional decoration. The NGram logits processor suppresses the repetition loops OCR models fall into on tables and dense layouts — vLLM's recipe calls it important for optimal OCR and markdown output — and prefix caching plus the multimodal processor cache are explicitly disabled per the same recipe. For offline batch processing, the official README's snippet:

from vllm import LLM, SamplingParams
from vllm.model_executor.models.deepseek_ocr import NGramPerReqLogitsProcessor
from PIL import Image

llm = LLM(
    model="deepseek-ai/DeepSeek-OCR",
    enable_prefix_caching=False,
    mm_processor_cache_gb=0,
    logits_processors=[NGramPerReqLogitsProcessor],
)

image = Image.open("page_001.png").convert("RGB")
prompt = "<image>\nFree OCR."

sampling = SamplingParams(
    temperature=0.0,
    max_tokens=8192,
    extra_args=dict(
        ngram_size=30,
        window_size=90,
        whitelist_token_ids={128821, 128822},  # <td>, </td>
    ),
    skip_special_tokens=False,
)

outputs = llm.generate(
    [{"prompt": prompt, "multi_modal_data": {"image": image}}], sampling
)
print(outputs[0].outputs[0].text)

The whitelisted token IDs keep table cell tags available to the anti-repetition filter — copy them as-is. Temperature 0.0 is deliberate: OCR is transcription, not creativity. One sizing note: vLLM preallocates 90% of your GPU memory by default (gpu_memory_utilization=0.9, per vLLM's docs), which is the right behavior on a dedicated box and an unpleasant surprise on your desktop. New to vLLM? Start with our complete vLLM setup guide — everything there applies here.

For calibration on throughput: the repo's own PDF concurrency figure is ~2,500 tokens/second on an A100-40G, the setup behind that 200K+ pages/day claim. A consumer card will be slower; the paper offers no consumer-GPU numbers, and we won't invent any.

---

Reference Path: Transformers {#transformers}

Use this path when you want the exact environment DeepSeek tested, or when you're running DeepSeek-OCR 2, which has no Ollama package (serve it with vLLM instead — upstream support landed in February 2026). The repo pins everything:

git clone https://github.com/deepseek-ai/DeepSeek-OCR.git
conda create -n deepseek-ocr python=3.12.9 -y
conda activate deepseek-ocr
pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 \
  --index-url https://download.pytorch.org/whl/cu118
pip install -r requirements.txt
pip install flash-attn==2.7.3 --no-build-isolation

(The repo additionally installs a vLLM 0.8.5 wheel for its bundled batch scripts; skip it if you only want the transformers path.) Inference follows the README:

from transformers import AutoModel, AutoTokenizer
import torch

model_name = "deepseek-ai/DeepSeek-OCR"
tokenizer = AutoTokenizer.from_pretrained(model_name, trust_remote_code=True)
model = AutoModel.from_pretrained(
    model_name,
    _attn_implementation="flash_attention_2",
    trust_remote_code=True,
    use_safetensors=True,
)
model = model.eval().cuda().to(torch.bfloat16)

prompt = "<image>\n<|grounding|>Convert the document to markdown. "
res = model.infer(
    tokenizer, prompt=prompt, image_file="invoice.png",
    output_path="out/", base_size=1024, image_size=640,
    crop_mode=True, save_results=True,
)

Note trust_remote_code=True: the model ships its own architecture code, which transformers executes on your machine. That is normal for research releases and a real supply-chain consideration for production — pin the revision if it matters to you.

---

Prompts and Resolution Modes {#prompts-modes}

The prompt selects the task, and <|grounding|> is the switch most people miss — without it you get plain text, with it you get structured markdown plus layout boxes. The official prompt list:

# document -> markdown (tables, structure):
"<image>\n<|grounding|>Convert the document to markdown."
# plain text, no layout:
"<image>\nFree OCR."
# OCR a photo or screenshot:
"<image>\n<|grounding|>OCR this image."
# extract charts/figures from a page:
"<image>\nParse the figure."
# general description:
"<image>\nDescribe this image in detail."
# find specific text on the page:
"<image>\nLocate <|ref|>your text<|/ref|> in the image."

Resolution modes trade accuracy against token spend — this table is straight from the official README:

Small mode's 100 tokens is the configuration behind the headline OmniDocBench result. Practical guidance: clean digital PDFs read fine at Small; scanned pages, small fonts and dense tables deserve Base or Large; Gundam mode tiles very large pages dynamically. In the transformers path you steer this with base_size / image_size / crop_mode — the README's example (1024/640/crop) is the dynamic setting.

---

DeepSeek-OCR 2: What Changed {#deepseek-ocr-2}

DeepSeek-OCR 2 landed January 27, 2026 — a new encoder, not a bigger model — and for most local users v1 is still the one to run today.

The headline idea (arXiv 2601.20552, "Visual Causal Flow"): DeepEncoder V2 dynamically reorders visual tokens based on what the image means instead of scanning in fixed left-to-right raster order — closer to how a human eye actually traverses an invoice or a two-column paper. The open release uses a single dynamic-resolution mode: up to six 768x768 tiles plus one 1024x1024 global view — up to ~1,120 visual tokens, per its README — with weights again a single safetensors file at 6.78GB, barely larger than v1. One licensing note: v2 ships under Apache-2.0, where v1 is MIT.

Why we still point you at v1 for daily work, as of early August 2026:

• Tooling. v1 has an official Ollama package and upstream vLLM support. OCR 2's own README documents the same pinned CUDA 11.8 / torch 2.6.0 environment with its own scripts; vLLM's recipes repo has since added a DeepSeek-OCR-2 recipe, but there is still no Ollama package.
• Maturity. The v2 repo sits at 3,232 stars to v1's 23,743; the ecosystem of integrations, bug reports and third-party benchmarks around v1 simply doesn't exist for v2 yet.
• Same footprint, same interface. The prompts are unchanged (<|grounding|>Convert the document to markdown. and Free OCR.), so switching later is cheap.

If you want to try it anyway, follow the transformers path above with model_name = "deepseek-ai/DeepSeek-OCR-2" — its README mirrors v1's flow, built around 768-pixel tiles. Expect the remaining gap to close: the vLLM recipes repo already carries an OCR 2 recipe, so an Ollama package is the missing piece.

---

Honest Limitations {#limitations}

DeepSeek-OCR is the best open document-OCR engine you can self-host right now, and it is still not magic. What to know before you build on it:

• Accuracy degrades with compression — by design. The paper's own curve: ~97% precision under 10x compression, ~60% at 20x. If you run Tiny mode on a dense page you are choosing that lower bound. For anything where a wrong digit costs money, use Base or Large and verify critical fields.
• It transcribes; it doesn't understand. DeepSeek-OCR is a specialist. Asking it about the document — "what's the total including VAT?" — is a job for a general vision model like Qwen3-VL, or for an LLM downstream of the OCR output.
• Wrong-but-fluent failure mode. Like every VLM-based OCR, when it fails it produces plausible text rather than visible garbage — the opposite of classic OCR engines, whose failures at least look broken. Spot-check anything load-bearing.
• No PDFs in, no native batching outside vLLM. Everything wants images; page rasterization is on you.
• NVIDIA-first. The pinned environment is CUDA; the vLLM recipe adds ROCm instructions for datacenter-class AMD GPUs (MI300X-series, ROCm 7.0), but consumer AMD and Apple Silicon users are not the target audience here. On a Mac, Ollama is the only sanctioned route.
• No official quantized weights. BF16 or nothing from DeepSeek — the VRAM bar stays where it is until someone you trust ships a quant.

Where it lands after all that: for turning paper into structured, searchable markdown — feeding a local RAG pipeline or a document summarizer — nothing open comes close at this token cost.

---

Alternatives Worth Knowing {#alternatives}

OCR VLMs iterate roughly every six months, so know the field. Star counts read from the GitHub API on August 5, 2026:

(Sizes and language counts per each project's own README or model card.) If your documents are mostly photos of text in the wild rather than documents, or you need question-answering over the page, a general vision model is the better tool — start with our classic OCR tutorial for the traditional Tesseract-style baseline and Qwen3-VL locally for the do-everything option.

We'll keep this section current as the field moves — it has turned over twice since 2025 already.

---

Sources {#sources}

• DeepSeek-OCR GitHub repository — install environment, vLLM/transformers code, resolution modes, prompts, A100 throughput (read August 5, 2026)
• DeepSeek-OCR paper, arXiv 2510.18234 — compression/precision figures, OmniDocBench comparisons, architecture parameters, 200K pages/day claim
• DeepSeek-OCR 2 repository and arXiv 2601.20552 — DeepEncoder V2, dynamic-resolution mode, release date
• vLLM DeepSeek-OCR recipe — serve command, logits processor, cache flags, ROCm notes
• Hugging Face: deepseek-ai/DeepSeek-OCR — weight file sizes, MIT license
• Ollama library: deepseek-ocr — package size, pull count, v0.13.0 requirement, context window
• GitHub API — star counts for all repos cited, August 5, 2026. Install commands in this guide are transcribed from the official docs above, not re-typed from memory; VRAM comfort levels are our estimates from published weight sizes and are labeled as such.

---

FAQ {#faq}