> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/QwenLM/Qwen3-VL/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install transformers, qwen-vl-utils, and dependencies to get started with Qwen3-VL.

## Prerequisites

Before installing Qwen3-VL, ensure you have:

> **Python**
>
> Python 3.8 or higher

> **CUDA**
>
> NVIDIA GPU with CUDA support (recommended)

> **PyTorch**
>
> PyTorch 2.0 or higher

> **pip**
>
> pip package manager

## Basic Installation

**1. Install Transformers**

Qwen3-VL requires transformers version 4.57.0 or higher:

```bash theme={null}
pip install "transformers>=4.57.0"
```

> [!NOTE]
>
> This is the minimum requirement to run Qwen3-VL with Hugging Face Transformers.

**2. Install qwen-vl-utils (Optional but Recommended)**

For advanced vision processing capabilities:

```bash theme={null}
pip install qwen-vl-utils==0.0.14
```

> [!TIP]
>
> For faster video loading, install with the `decord` feature:
>
> ```bash theme={null}
> pip install "qwen-vl-utils[decord]"
> ```

**3. Verify Installation**

Test your installation:

```python theme={null}
from transformers import AutoModelForImageTextToText, AutoProcessor

# This should run without errors
processor = AutoProcessor.from_pretrained("Qwen/Qwen3-VL-2B-Instruct")
print("Installation successful!")
```

## Performance Optimizations

### Flash Attention 2

For significantly faster inference, especially with multi-image and video scenarios:

```bash theme={null}
pip install -U flash-attn --no-build-isolation
```

> [!WARNING]
>
> Flash Attention 2 requires:
>
> * Compatible NVIDIA GPU (Ampere or newer)
> * CUDA 11.6 or higher
> * Models loaded in `torch.float16` or `torch.bfloat16`

Usage example:

```python theme={null}
import torch
from transformers import AutoModelForImageTextToText

model = AutoModelForImageTextToText.from_pretrained(
    "Qwen/Qwen3-VL-235B-A22B-Instruct",
    torch_dtype=torch.bfloat16,
    attn_implementation="flash_attention_2",
    device_map="auto",
)
```

### Video Processing Backends

Qwen3-VL supports multiple video decoding backends:

**torchcodec (Recommended)**

Best performance and compatibility:

```bash theme={null}
# Follow official installation instructions
# https://github.com/pytorch/torchcodec
```

> [!NOTE]
>
> Supports both HTTP and HTTPS URLs. Requires FFmpeg.

**decord**

Fast decoding for Linux users:

```bash theme={null}
pip install "qwen-vl-utils[decord]"
```

> [!WARNING]
>
> * Only supports HTTP URLs (not HTTPS)
> * May have decoding issues on some videos
> * Project is no longer actively maintained

**torchvision**

Default fallback option:

```bash theme={null}
# Already included with transformers
```

> [!NOTE]
>
> * torchvision >= 0.19.0 supports HTTP and HTTPS
> * Older versions have no URL support
> * Slower than decord and torchcodec

Switch backends by setting an environment variable:

```bash theme={null}
export FORCE_QWENVL_VIDEO_READER=torchcodec  # or decord, torchvision
```

## Deployment Installation

For production deployment with vLLM or SGLang:

```bash vLLM theme={null}
# Install accelerate and qwen-vl-utils
pip install accelerate
pip install qwen-vl-utils==0.0.14

# Install latest vLLM (>= 0.11.0)
uv pip install -U vllm
```

```bash SGLang theme={null}
# Install SGLang
pip install sglang[all]

# Install qwen-vl-utils
pip install qwen-vl-utils==0.0.14
```

> [!NOTE]
>
> For detailed deployment instructions, see the [Deployment Guide](https://mintlify.com/QwenLM/Qwen3-VL/deployment/overview.md).

## China Mainland Users

For users in mainland China, we recommend using ModelScope:

```python theme={null}
from modelscope import snapshot_download

# Download model checkpoint
model_dir = snapshot_download('qwen/Qwen3-VL-8B-Instruct')

# Load from local directory
from transformers import AutoModelForImageTextToText
model = AutoModelForImageTextToText.from_pretrained(
    model_dir,
    dtype="auto",
    device_map="auto"
)
```

## Docker Installation

Use our pre-built Docker images for a simplified setup:

```bash theme={null}
docker run --gpus all --ipc=host --network=host --rm --name qwen3vl \
  -it qwenllm/qwenvl:qwen3vl-cu128 bash
```

> [!TIP]
>
> The Docker image includes:
>
> * Pre-configured environment
> * All dependencies
> * CUDA 12.8 support
>
> You only need to install GPU drivers on the host machine.

## Installation Verification

Run this complete test to verify your installation:

```python theme={null}
from transformers import AutoModelForImageTextToText, AutoProcessor
import torch

print("Testing Qwen3-VL installation...")

# Check transformers version
import transformers
print(f"Transformers version: {transformers.__version__}")
assert transformers.__version__ >= "4.57.0", "Please upgrade transformers"

# Check CUDA availability
print(f"CUDA available: {torch.cuda.is_available()}")
if torch.cuda.is_available():
    print(f"CUDA version: {torch.version.cuda}")
    print(f"GPU count: {torch.cuda.device_count()}")

# Try loading processor
try:
    processor = AutoProcessor.from_pretrained("Qwen/Qwen3-VL-2B-Instruct")
    print("✓ Processor loaded successfully")
except Exception as e:
    print(f"✗ Error loading processor: {e}")

# Check qwen-vl-utils
try:
    import qwen_vl_utils
    print(f"✓ qwen-vl-utils version: {qwen_vl_utils.__version__}")
except ImportError:
    print("○ qwen-vl-utils not installed (optional)")

# Check flash-attn
try:
    import flash_attn
    print("✓ Flash Attention 2 available")
except ImportError:
    print("○ Flash Attention 2 not installed (optional)")

print("\nInstallation verification complete!")
```

## Troubleshooting

> **ModuleNotFoundError: No module named 'transformers'**
>
> Make sure you've installed transformers:
>
> ```bash theme={null}
> pip install "transformers>=4.57.0"
> ```

> **CUDA out of memory**
>
> Try these solutions:
>
> 1. Use a smaller model (e.g., 2B or 4B instead of 235B)
> 2. Enable quantization with FP8 models
> 3. Use `device_map="auto"` for automatic device placement
> 4. Reduce batch size or max\_new\_tokens
>
> ```python theme={null}
> # Use FP8 quantized model
> model = AutoModelForImageTextToText.from_pretrained(
>     "Qwen/Qwen3-VL-8B-Instruct-FP8",
>     dtype="auto",
>     device_map="auto"
> )
> ```

> **Flash Attention installation fails**
>
> Flash Attention 2 requires:
>
> * NVIDIA GPU with Ampere architecture or newer
> * CUDA 11.6+
> * Proper build tools
>
> If installation fails, you can skip it and use default attention:
>
> ```python theme={null}
> # Don't specify attn_implementation
> model = AutoModelForImageTextToText.from_pretrained(
>     "Qwen/Qwen3-VL-8B-Instruct",
>     dtype="auto",
>     device_map="auto"
> )
> ```

> **Video decoding errors**
>
> If you encounter video processing issues:
>
> 1. Try a different backend:
>    ```bash theme={null}
>    export FORCE_QWENVL_VIDEO_READER=torchcodec
>    ```
>
> 2. Ensure you have the required dependencies:
>    * torchcodec: Requires FFmpeg
>    * decord: Linux only, may need to build from source
>    * torchvision: Requires version >= 0.19.0 for URL support
>
> 3. Use local video files instead of URLs as a workaround

## Next Steps

Now that you have Qwen3-VL installed, you can:

> **[Quick Start](https://mintlify.com/QwenLM/Qwen3-VL/quickstart.md)**
>
> Run your first inference with an image

> **[Advanced Usage](https://mintlify.com/QwenLM/Qwen3-VL/inference/pixel-control.md)**
>
> Learn about pixel control, batching, and optimization

> **[Deployment](https://mintlify.com/QwenLM/Qwen3-VL/deployment/overview.md)**
>
> Deploy Qwen3-VL with vLLM or SGLang

> **[Cookbooks](https://github.com/QwenLM/Qwen3-VL/tree/main/cookbooks)**
>
> Explore practical examples and use cases


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.