Installation

The Vi SDK runs on Python 3.10 through 3.14 on Linux, macOS, and Windows. This page covers installation options, virtual environment setup, GPU configuration, and troubleshooting common issues.

Requirements

Check your Python version before installing:

The output should show Python 3.10 or higher.

Basic installation

The base install includes API functionality for:

• Dataset management
• Asset upload and download
• Annotation workflows
• Model operations

Optional feature sets

Install additional features as your workflow requires them.

Inference support

For running inference locally with vision-language models (Qwen2.5-VL, Qwen3-VL, Qwen3.5/3.6, Gemma 4, InternVL 3.5, LLaVA-NeXT, Cosmos Reason1/2, DeepSeek-OCR, NVILA):

Jupyter notebook support

For proper rich formatting and progress tracking in Jupyter notebooks:

Deployment support

For the OpenAI-compatible local inference server and NVIDIA NIM containers:

Dataset loaders

For the HuggingFace datasets integration used by the PyTorch dataset loaders:

All features

Virtual environment setup

A virtual environment keeps Vi SDK's dependencies separate from other Python projects. This prevents version conflicts and makes your environment reproducible.

GPU support for inference

A GPU is not required for the base SDK or dataset operations, but it makes a significant difference for local inference. CPU inference works for development and small-scale testing.

NVIDIA GPUs (CUDA)

Verify CUDA is available:

import torch

print(f"CUDA available: {torch.cuda.is_available()}")
print(f"CUDA version: {torch.version.cuda}")
print(f"GPU count: {torch.cuda.device_count()}")
if torch.cuda.is_available():
    print(f"GPU name: {torch.cuda.get_device_name(0)}")

Apple Silicon (MPS)

PyTorch detects and uses Metal Performance Shaders automatically on Apple Silicon Macs with macOS 12.3+:

import torch

print(f"MPS available: {torch.backends.mps.is_available()}")
print(f"MPS built: {torch.backends.mps.is_built()}")

CPU only

Performance reference:

Verifying the install

import vi

print(f"Vi SDK version: {vi.__version__}")

from vi import Client
from vi.dataset.loaders import ViDataset
print("Core modules loaded.")

Platform-specific setup

Linux

macOS

Windows

Upgrading

Check your current version:

import vi
print(vi.__version__)

Uninstalling

To remove everything including the virtual environment:

Troubleshooting

from vi.inference import ViModel

model = ViModel(
    secret_key="your-key",
    organization_id="your-org",
    run_id="your-run",
    load_in_4bit=True  # 4-bit quantization reduces VRAM usage
)

# Also try reducing batch size
results = model(
    source=images,
    user_prompt="...",
    batch_size=1
)

Next steps