Qwen 3 VL Local Setup Guide (2026): The Best Open Vision-Language Model

Qwen3-VL is Alibaba's vision-language family and the default open-weights choice for running image, document and video understanding locally. It ships as 2B / 4B / 8B / 32B dense models plus two mixture-of-experts models (30B-A3B and 235B-A22B), each in Instruct and Thinking versions, under the Apache 2.0 license. Native 256K context (expandable to 1M), OCR in 32 languages, multi-image reasoning, chart and table understanding, and hours-long video with timestamp grounding. For local document analysis, video Q&A, accessibility tools and visual chatbots, it is the open model to start with in 2026.

This guide covers the Qwen3-VL family, the Ollama tags that actually exist, setup across Ollama / vLLM / llama.cpp, image and video input formats, OCR and document workflows, fine-tuning, and how it compares with Llama 3.2 Vision, Pixtral and GPT-4o on licensing and features. Updated November 2, 2026: sizes and tags re-checked against the Ollama registry and the Qwen3-VL model cards.

Table of Contents

1. What Qwen 3 VL Is
2. Family: 2B / 4B / 8B / 32B + MoE
3. Hardware Requirements
4. Qwen 3 VL vs Llama 3.2 Vision vs Pixtral vs GPT-4o
5. vLLM Setup
6. Ollama Setup
7. llama.cpp / GGUF Setup
8. Image Input Format
9. Video Understanding
10. OCR and Document Analysis
11. Multi-Image Reasoning
12. Multilingual Vision
13. Fine-Tuning
14. Speed and Memory
15. Tuning Recipes
16. Production Deployment
17. Licensing
18. Troubleshooting
19. FAQ

---

What Qwen 3 VL Is

Qwen3-VL (Qwen/Qwen3-VL-* on Hugging Face, QwenLM/Qwen3-VL on GitHub) is Alibaba's vision-language family: a Qwen3 language model plus a ViT vision encoder. Qwen lists three architecture changes over Qwen2.5-VL — Interleaved-MRoPE positional embeddings across time, width and height for long video, DeepStack fusion of multi-level ViT features for finer detail, and text-timestamp alignment for locating events in video. License: Apache 2.0.

Release timeline (from the Qwen3-VL GitHub news log):

• September 23, 2025 — Qwen3-VL-235B-A22B (Instruct and Thinking)
• October 4, 2025 — Qwen3-VL-30B-A3B, plus FP8 versions
• October 15, 2025 — Qwen3-VL-4B and 8B
• October 21, 2025 — Qwen3-VL-2B and 32B

Capabilities Qwen lists:

• High-fidelity image understanding
• OCR in 32 languages (up from 10), more robust to blur, low light and tilted pages
• Chart, table and equation parsing
• Multi-image reasoning (compare two images, find differences)
• Hours-long video with second-level indexing
• Native 256K context (text + visual tokens), expandable to 1M with YaRN

---

Family: 2B / 4B / 8B / 32B + MoE

Sizes from the Ollama registry (November 2, 2026); the 4B and 8B include a separate vision projector. There is no 7B or 72B Qwen3-VL — those sizes belong to Qwen2.5-VL (qwen2.5vl:7b, qwen2.5vl:72b).

For most local users: the 8B. Thinking variants (qwen3-vl:8b-thinking) reason step by step before answering, at the cost of more tokens.

---

Hardware Requirements

Image and video tokens sit on top of the weights; large images and long clips need several extra GB of headroom.

---

Qwen 3 VL vs Llama 3.2 Vision vs Pixtral vs GPT-4o

Qwen's published benchmark scores (Instruct models)

These are Qwen's own numbers, copied from the benchmark charts on the official Hugging Face model cards (Qwen/Qwen3-VL-2B-Instruct, -4B, -8B and -32B, checked November 2, 2026). Qwen notes that the evaluations were run through API calls and that video results use a 256K-token context with up to 2,048 frames. They are vendor-reported, not independent:

Source: benchmark charts on the Qwen3-VL Instruct model cards on Hugging Face (released October 2025); the Qwen3-VL Technical Report (arXiv, November 26, 2025) describes the evaluation. The 30B-A3B and 235B-A22B models have their own tables on their model cards.

Two things stand out in Qwen's own numbers: the 8B is within a point or two of the 32B on document benchmarks (DocVQA, OCRBench), and the gap opens on reasoning-heavy tests (MMMU, MathVista) and video. That fits the sizing advice above: the 8B as the default for OCR and document work, the 32B when you need harder reasoning and have the VRAM.

Qwen also notes that some prompts were modified and some benchmarks are internally constructed, and each vendor evaluates differently, so we do not merge these with other vendors' scores into one cross-vendor table. The practical test is a sample of your own images and documents run through the 8B and one alternative.

---

vLLM Setup

Qwen3-VL needs vLLM 0.11.0 or newer:

vllm serve Qwen/Qwen3-VL-8B-Instruct \
    --max-model-len 32768 \
    --limit-mm-per-prompt '{"image": 4, "video": 1}' \
    --enable-prefix-caching

For the 32B in FP8 (Qwen publishes official FP8 checkpoints):

vllm serve Qwen/Qwen3-VL-32B-Instruct-FP8 \
    --tensor-parallel-size 2 \
    --max-model-len 32768

--limit-mm-per-prompt controls max images/videos per request.

---

Ollama Setup

ollama run qwen3-vl:8b

Pass images via the API (Ollama accepts images, not video):

curl http://localhost:11434/api/chat -d '{
  "model": "qwen3-vl:8b",
  "messages": [{
    "role": "user",
    "content": "What is in this image?",
    "images": ["base64-encoded-image"]
  }]
}'

---

llama.cpp / GGUF Setup

Qwen publishes official GGUF files, with the vision projector as a separate mmproj file:

huggingface-cli download Qwen/Qwen3-VL-8B-Instruct-GGUF \
    Qwen3VL-8B-Instruct-Q4_K_M.gguf \
    mmproj-Qwen3VL-8B-Instruct-F16.gguf \
    --local-dir ./models

./llama-mtmd-cli \
    -m models/Qwen3VL-8B-Instruct-Q4_K_M.gguf \
    --mmproj models/mmproj-Qwen3VL-8B-Instruct-F16.gguf \
    -ngl 999 -c 32768 \
    --image picture.jpg \
    -p "Describe this image."

The mmproj file is the vision projector — required for image input. The repo also has Q8_0 and F16 weights.

---

Image Input Format

OpenAI-compatible:

{
  "model": "qwen3-vl:8b",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Describe this image in detail."},
      {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}}
    ]
  }]
}

Qwen3-VL handles arbitrary image resolutions via dynamic patching. Bigger images cost more visual tokens, so pre-resize to roughly 1024-2048px on the long side unless you need fine print.

---

Video Understanding

Video needs vLLM or transformers; Ollama does not take video input.

{
  "model": "Qwen/Qwen3-VL-8B-Instruct",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Summarize this video and identify key moments."},
      {"type": "video_url", "video_url": {"url": "file:///path/to/video.mp4"}}
    ]
  }]
}

Qwen's processor example samples at 2 fps and caps the visual tokens per video (256-16,384 in the README). For long videos, reduce the sampling rate or pre-segment.

Use cases:

• Video Q&A: "What happened at 12:30?"
• Summarization
• Scene search
• Accessibility (audio description)
• Sports analysis
• Security camera review

---

OCR and Document Analysis

For document workflows:

{
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Extract all text from this invoice as JSON: {invoice_number, date, vendor, line_items, total}"},
      {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}}
    ]
  }],
  "response_format": {"type": "json_schema", "json_schema": {...}}
}

Qwen3-VL handles:

• Printed text in 32 languages (Qwen's count)
• Handwriting (variable; test on your own samples)
• Tables (preserves structure)
• Charts (extracts data points)
• Equations (outputs LaTeX)
• Forms with checkboxes

For bulk speed-optimized OCR, use Tesseract or PaddleOCR, which are much lighter but lack reasoning. Qwen3-VL is for OCR + downstream reasoning in one shot.

---

Multi-Image Reasoning

{
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "What changed between these two images?"},
      {"type": "image_url", "image_url": {"url": "image1.jpg"}},
      {"type": "image_url", "image_url": {"url": "image2.jpg"}}
    ]
  }]
}

Several images fit in one request as long as their visual tokens fit the context you set. Useful for: before/after comparison, finding the odd-one-out, sequence understanding, comic / storyboard analysis.

---

Multilingual Vision

Qwen expanded OCR from 10 languages in Qwen2.5-VL to 32 in Qwen3-VL, and says it handles rare and ancient characters and technical jargon better. Chinese and English are its strongest languages, as for every Qwen model. Accuracy still varies by script, font and image quality, so for production on a specific language or script, validate on a labelled sample and fine-tune if needed.

---

Fine-Tuning

Use LLaMA-Factory (check its supported-models list for the current Qwen3-VL template name) or transformers + PEFT:

# LLaMA-Factory
llamafactory-cli train \
    --model_name_or_path Qwen/Qwen3-VL-8B-Instruct \
    --finetuning_type lora \
    --dataset my_vision_dataset \
    --template qwen3_vl \
    --output_dir ./qwen3vl_lora

Qwen3-VL requires transformers 4.57.0 or newer. For domain adaptation (medical imaging, legal contracts, manufacturing QA), start with a few hundred to a few thousand labelled image+text pairs and measure on a held-out set before scaling up.

---

Speed and Memory

There is no measured Qwen3-VL row in our benchmark table, so here is what bounds speed instead. Text generation is limited by memory bandwidth divided by model size: on an RTX 4090 (1,008 GB/s, NVIDIA), the 8B's 5.0 GB of language weights gives a ~200 tok/s ceiling and the 32B's 21 GB a ~48 tok/s ceiling. The 30B-A3B is a mixture-of-experts model, so a simple ceiling does not apply. Real speed lands below the ceiling.

Memory: the weights (table above) plus visual tokens and KV cache; video sequences add the most.

---

Tuning Recipes

Document OCR pipeline

vllm serve Qwen/Qwen3-VL-8B-Instruct \
    --max-model-len 16384 \
    --limit-mm-per-prompt '{"image": 10}' \
    --enable-prefix-caching

Fixed system prompt with extraction template; benefit from prefix cache.

Video Q&A server

vllm serve Qwen/Qwen3-VL-32B-Instruct-FP8 \
    --tensor-parallel-size 2 \
    --max-model-len 65536 \
    --limit-mm-per-prompt '{"image": 64, "video": 1}'

Long context needed for long videos.

Multi-language document workflow

Use the 32B for harder non-English documents; the 8B for English-only at higher throughput.

---

Production Deployment

For high-throughput document processing (1000s of docs/day):

vllm serve Qwen/Qwen3-VL-8B-Instruct \
    --max-model-len 16384 \
    --max-num-seqs 32 \
    --enable-prefix-caching --enable-chunked-prefill \
    --kv-cache-dtype fp8_e4m3

Pair with LocalAI for OpenAI-compatible images endpoint, or LiteLLM gateway for routing.

---

Licensing

Apache 2.0 (per the Qwen3-VL repository and model cards). Commercial use, modification and redistribution are allowed with no user-count or regional restrictions; keep the license notice.

Other permissively licensed options: Pixtral (Apache 2.0) and Phi-4-multimodal (MIT). Llama 3.2 Vision uses Meta's community license, whose acceptable-use policy does not grant multimodal rights to EU-domiciled individuals and companies.

---

Troubleshooting

---

FAQ

See answers to common Qwen 3 VL questions below.

---

Sources: QwenLM/Qwen3-VL on GitHub (release dates, license, context, OCR languages, version requirements) | Qwen3-VL Instruct model cards (2B, 4B, 8B, 32B; benchmark scores, checked November 2, 2026) | Qwen3-VL Technical Report | Ollama qwen3-vl library (tags and sizes, read November 2, 2026) | vLLM multimodal docs | Llama 3.2 acceptable use policy.

Related guides:

• Qwen 3 Local Setup Guide
• Multimodal AI Standard
• Local AI Document Scanner
• Phi-4 Local Setup
• ComfyUI Complete Guide
• vLLM Complete Setup Guide