Install & Compatibility
Where this runs
tested against v0.0.9 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ dependency_conflict
4/8 runs
py 3.11
✕ dependency_conflict
4/8 runs
py 3.12
✕ dependency_conflict
4/8 runs
py 3.13
✕ no_wheel
4/8 runs
py 3.9
✕ dependency_conflict
4/8 runs
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
process_mm_info
✓ from qwen_omni_utils import process_mm_info
The primary utility function for preparing multimodal inputs for Qwen models.
This quickstart demonstrates how to import `process_mm_info` from `qwen_omni_utils`. While it shows how model and processor loading would typically be done, the actual heavy model loading and inference steps are commented out due to resource requirements. The `process_mm_info` function is key for preparing diverse multimodal inputs for the Qwen Omni models. Ensure you have `ffmpeg` installed for full video capabilities and a compatible `transformers` version.
import soundfile as sf
import torch
from transformers import Qwen2_5OmniForConditionalGeneration, Qwen2_5OmniProcessor
from qwen_omni_utils import process_mm_info
import os
# NOTE: Replace with your actual model path or Hugging Face model ID
model_id = "Qwen/Qwen2.5-Omni-7B"
# Ensure you have a Hugging Face token if using private models
# os.environ['HF_TOKEN'] = os.environ.get('HF_TOKEN', 'hf_YOUR_TOKEN_HERE')
# Load model and processor (requires significant GPU memory)
# model = Qwen2_5OmniForConditionalGeneration.from_pretrained(
# model_id, torch_dtype="auto", device_map="auto"
# )
# processor = Qwen2_5OmniProcessor.from_pretrained(model_id)
# Example usage with process_mm_info (assuming model/processor loaded above)
# This function prepares multimodal content for the processor.
# content = [
# {"type": "text", "text": "Describe this image:"},
# {"type": "image", "image": "https://example.com/image.jpg"},
# {"type": "text", "text": "And tell me about this audio:"},
# {"type": "audio", "audio": "https://example.com/audio.wav"}
# ]
# processed_content = process_mm_info(content, processor)
print("qwen-omni-utils is successfully imported and ready to process multimodal inputs.")
print("Refer to Qwen model documentation for full model loading and inference examples.")
Debug
Known issues
breakingThe GitHub repository for `qwen-omni-utils` can be significantly out of sync with the PyPI release. New features or fixes present in the PyPI package might not be reflected in the public GitHub source code for the utility, leading to confusion when reviewing source or contributing.fixAlways install the PyPI version (`pip install qwen-omni-utils`) for the most up-to-date and functional code. Refer to PyPI for declared dependencies and changelogs over GitHub source for `qwen-omni-utils` itself.
affects: All versions
gotchaStrict `transformers` library version compatibility is often required for Qwen Omni models. Using an incompatible `transformers` version can lead to `KeyError: 'qwen2_5_omni'` or other model loading failures.fixRefer to the specific Qwen model's Hugging Face page or documentation for the exact recommended `transformers` version. Often, installing `transformers` from a specific GitHub branch or commit is advised, e.g., `pip install git+https://github.com/huggingface/transformers@v4.51.3-Qwen2.5-Omni-preview`.
affects: All versions
gotcha`decord` for faster video loading might not install correctly from PyPI on non-Linux systems. If `decord` installation fails, `qwen-omni-utils` will fall back to `torchvision` for video processing, which might be slower.fixOn non-Linux systems, either accept `torchvision` as a fallback or compile `decord` from source if optimal video performance is critical. Ensure `ffmpeg` is installed, as it's a general prerequisite for multimedia handling.
affects: All versions
gotchaWhen integrating `qwen-omni-utils` with `vLLM` for inference, users have reported issues where text generation either cuts off abruptly or enters an infinite repetition loop. This is linked to internal differences in how `positions`, `eager`, and `CUDA` parameters are handled within `Qwen2Attention` module in `vLLM`.fixMonitor `vLLM` and Qwen model GitHub issues for updates and specific patches related to `Qwen2Attention` module compatibility. If encountering this, try different `vLLM` versions or avoid streaming generation with `qwen-omni-utils` if possible.
affects: All versions with `vLLM` 0.8.5 and potentially others.
Upgrade
Version history
0.0.9latest on PyPI · released Feb 10, 2026
Audit
Dependencies
avrequiredRequired for multimedia processing.
librosarequiredRequired for audio processing.
packagingrequiredRequired for version parsing and compatibility checks.
pillowrequiredRequired for image processing.
requestsrequiredRequired for fetching content from URLs.
decordoptionalOptional, highly recommended for faster video loading.
torchvisionoptionalFallback for video processing if 'decord' is not installed, especially on non-Linux systems.
transformersrequiredCrucial for interacting with Qwen Omni models and their processors. Specific versions may be required for compatibility.