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, InternVL 3.5, Cosmos Reason1, NVILA):

Jupyter notebook support

For proper rich formatting and progress tracking in Jupyter notebooks:

Deployment support

For deploying models with NVIDIA NIM containers:

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.

venv is included with Python and needs no additional install.

Install conda via [Miniconda](https://docs.conda.io/en/latest/miniconda.html).

uv is a fast alternative to pip and virtualenv.

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

Next steps