Installation

Requirements

Before installing Vi SDK, ensure your system meets these requirements:

💡

Python version check

Verify your Python version:

Bash

python --version
# or
python3 --version

Output should show Python 3.10 or higher.

Basic installation

The simplest way to install Vi SDK is using pip:

pip install vi-sdk

This installs the core SDK with all essential features:

• ✅ Dataset management
• ✅ Asset upload/download operations
• ✅ Annotation workflows
• ✅ Model operations
• ✅ API client functionality
• ✅ Progress tracking and logging

Installation with optional features

Vi SDK provides optional feature sets that can be installed as needed.

Inference support

For running inference with vision-language models (Qwen2.5-VL, InternVL 3.5, Cosmos Reason1, NVILA):

pip install vi-sdk[inference]

Includes:

• transformers — Hugging Face Transformers for model loading
• torch — PyTorch for deep learning
• torchvision — Computer vision utilities
• xgrammar — Structured output generation
• accelerate — Model acceleration utilities
• bitsandbytes — Quantization support (Linux/Windows only)
• peft — Parameter-efficient fine-tuning

Jupyter notebook support

For using Vi SDK in Jupyter notebooks:

pip install vi-sdk[jupyter]

Includes:

• ipykernel — Jupyter kernel support
• ipywidgets — Interactive widgets

Deployment support

For deploying models with NIM (NVIDIA Inference Microservices):

pip install vi-sdk[deployment]

Includes:

• docker — Docker SDK for container management
• openai — OpenAI client for NIM API
• All inference dependencies

All features

To install everything:

pip install vi-sdk[all]

This includes all optional dependencies for the complete Vi SDK experience.

Virtual environment (recommended)

We strongly recommend using a virtual environment to avoid dependency conflicts.

# Create virtual environment
python3 -m venv vi-env

# Activate (Linux/macOS)
source vi-env/bin/activate

# Activate (Windows)
vi-env\Scripts\activate

# Install Vi SDK
pip install vi-sdk[all]

✅

Why use virtual environments?

Virtual environments:

• Isolate project dependencies
• Prevent version conflicts
• Allow different Python versions per project
• Make it easy to replicate environments

Choose your tool:

• venv — Built-in, no installation needed
• virtualenvwrapper — Convenient wrapper with simple commands
• conda — Popular in data science, manages Python versions
• uv — Ultra-fast alternative to pip and virtualenv

GPU support (for inference)

If you plan to use inference features, GPU acceleration significantly improves performance.

CUDA (NVIDIA GPUs)

For NVIDIA GPUs with CUDA support:

# Install PyTorch with CUDA 11.8 support
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

# Then install Vi SDK with inference
pip install vi-sdk[inference]

Check CUDA availability:

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)}")

MPS (Apple silicon)

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

pip install vi-sdk[inference]

Check MPS availability:

import torch

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

CPU only

If you don't have a GPU or prefer CPU-only inference:

# Install CPU-only PyTorch
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu

# Install Vi SDK with inference
pip install vi-sdk[inference]

📘

Performance Note

• GPU: Recommended for production inference (10-100x faster)
• Apple Silicon (MPS): Good performance for development and testing
• CPU: Suitable for small-scale inference and development

Verifying installation

After installation, verify that Vi SDK is working correctly:

import vi

# Check version
print(f"Vi SDK version: {vi.__version__}")
print("✓ Installation successful!")

# Test basic imports
from vi import Client
from vi.dataset.loaders import ViDataset
print("✓ Core modules loaded successfully!")

Expected output:

Vi SDK version: 0.1.0
✓ Installation successful!
✓ Core modules loaded successfully!

Platform-specific setup

Linux

Install system dependencies:

# Update package list
sudo apt-get update

# Install Python and pip
sudo apt-get install python3 python3-pip python3-venv

# Install development tools (optional)
sudo apt-get install build-essential python3-dev

macOS

Install Python using Homebrew:

# Install Homebrew (if not installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python
brew install [email protected]

# Verify installation
python3 --version

Windows

1. Download Python from python.org
2. Run the installer
3. Important: Check "Add Python to PATH" during installation
4. Verify installation in Command Prompt:
   cmd

   python --version
   pip --version

Upgrading Vi SDK

To upgrade to the latest version:

# Upgrade core SDK
pip install --upgrade vi-sdk

# Upgrade with all features
pip install --upgrade vi-sdk[all]

Check current version:

import vi
print(vi.__version__)

Uninstalling Vi SDK

To uninstall Vi SDK:

pip uninstall vi-sdk

To remove all dependencies (if installed via virtual environment):

# Deactivate virtual environment
deactivate

# Remove virtual environment directory
rm -rf vi-env  # Linux/macOS
# or
rmdir /s vi-env  # Windows

Troubleshooting common issues

# Verify installation location
pip show vi-sdk

# Install in current Python
python -m pip install vi-sdk

# Or check which Python you're using
which python  # Linux/macOS
where python  # Windows

# Create a fresh virtual environment
python -m venv fresh-env
source fresh-env/bin/activate  # or appropriate activation

# Install Vi SDK
pip install vi-sdk[all]

# If issues persist, upgrade pip
pip install --upgrade pip setuptools wheel

# Temporary fix (use with caution)
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org vi-sdk

# Better solution: Update certificates
pip install --upgrade certifi

# Option 1: Use --user flag
pip install --user vi-sdk

# Option 2: Use virtual environment (recommended)
python3 -m venv vi-env
source vi-env/bin/activate
pip install vi-sdk

# Check NVIDIA driver
nvidia-smi  # Should show GPU info

# Reinstall PyTorch with correct CUDA version
pip uninstall torch torchvision
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

# Verify
python -c "import torch; print(torch.cuda.is_available())"

# Use quantization for lower memory usage
from vi.inference import ViModel

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

# Or reduce batch size
results = model(
    source=images,
    user_prompt="...",
    batch_size=1  # Process one image at a time
)

Next steps

Now that you have Vi SDK installed: