Installation Guide¶

Use uv for an isolated CLI installation. This guide also covers existing virtual environments, source checkouts, and Docker.

System Requirements¶

Before installing Victor, ensure your system meets these requirements:

Requirement	Minimum	Recommended
Python	3.12+	3.12+
RAM	4 GB	8 GB+
Disk Space	500 MB	1 GB (for local models: 8-32 GB)
OS	Linux, macOS, Windows (WSL2)	Linux or macOS

Note: Windows users should use WSL2 (Windows Subsystem for Linux) for the best experience.

Installation Methods¶

Choose the installation method that best fits your use case:

Method	Command	Best For
uv (Recommended)	`uv tool install --python 3.12 victor-ai`	CLI users — no Python install needed (uv provisions one)
pipx	`pipx install --python python3.12 victor-ai`	Equivalent, if you already use pipx
pip	`pip install victor-ai`	Virtual environments, Python projects
Docker	`docker pull vjsingh1984/victor-ai`	Containers, isolated deployments
Development	`pip install -e ./victor-contracts -e ".[dev]"`	Contributors, local development

Method 1: uv (Recommended for CLI Users)¶

uv installs Victor in an isolated environment and
provisions its own Python — the host needs nothing but network access.

# Install uv if not already installed (macOS/Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Install Victor (uv fetches Python 3.12 if missing)
uv tool install --python 3.12 victor-ai

# Verify installation
victor --version

Why uv?
- No Python prerequisite — uv downloads a managed interpreter
- Isolates Victor's dependencies from your system Python
- Fast installs with a global wheel cache
- Easy upgrades with uv tool upgrade victor-ai
- Clean uninstalls with uv tool uninstall victor-ai

For coding, semantic search, and conversation checkpoints, install the matching
extras together. --force updates an existing tool installation and records the
extras in uv's tool receipt so future upgrades retain them:

uv tool install --force --python 3.12 "victor-ai[coding,embeddings,checkpoints]"
uv tool update-shell
# Open a new shell, or add uv's executable directory to PATH.
victor --version
victor doctor
victor onboarding --force

victor onboarding --force provides interactive provider and credential setup.
It displays dependency mismatches and a repair command before setup. It does not
install packages automatically. If your provider/profile is already configured,
skip onboarding and test it directly:

victor chat --profile YOUR_PROFILE "Reply exactly OK. Do not call tools."

If another virtual environment is active, its victor may shadow the uv tool.
Run deactivate, then hash -r and command -v victor (bash), or invoke
"$(uv tool dir --bin)/victor" explicitly. A Homebrew Python interpreter does not
mean Victor itself was installed by Homebrew; uv tool list identifies uv tools.

Updating after dependency pins change¶

A source pull does not reinstall dependencies or refresh editable package
metadata. Victor checks core requirements at chat startup, in victor doctor,
and during onboarding. An editable checkout is checked against its current
pyproject.toml; wheel installs use their packaged requirements. Mismatches
produce a warning with a repair command for the running environment. These checks
are offline, do not install anything, and do not infer which optional extras you
want. Use uv pip check --python PATH_TO_PYTHON for all installed distributions.

For the published CLI installation:

uv tool upgrade victor-ai
victor doctor

When testing source changes before a release, install from the intended checkout
so its dependency pins and first-party packages are resolved together:

cd /path/to/victor
uv tool install --force --python 3.12 \
  ".[coding,embeddings,checkpoints]" \
  --with ./victor-contracts --with ./verticals/victor-coding

For an existing development environment, refresh the editable installs explicitly
(use your actual environment path):

cd /path/to/victor
uv pip install --python ../.venv/bin/python \
  -e ".[coding,embeddings,checkpoints]" \
  -e ./victor-contracts -e ./verticals/victor-coding -e ./victor-codegraph
uv pip check --python ../.venv/bin/python
../.venv/bin/victor doctor

uv pip install retains unrelated packages in a shared environment. It can still
change shared dependency versions; inspect uv pip check results. Prefer the
isolated uv tool for daily CLI use. Rerun the source installation command after
pulling dependency changes; use uv tool upgrade for a published installation.
Do not independently override Sandhi's pinned version. Server credential setup
is separate; see the subscription gateway guide.

Method 2: pipx (Equivalent, If You Already Use It)¶

pipx installs Victor in an isolated environment, preventing dependency conflicts with other Python packages.

# Install pipx if not already installed
pip install pipx
pipx ensurepath

# Install Victor
pipx install --python python3.12 victor-ai

# Verify installation
victor --version

Why pipx?
- Isolates Victor's dependencies from your system Python
- Automatically adds victor to your PATH
- Easy upgrades with pipx upgrade victor-ai
- Clean uninstalls with pipx uninstall victor-ai

Method 3: pip (Virtual Environment)¶

For use within a Python virtual environment or project:

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install Victor
pip install victor-ai

# Verify installation
victor --version

Method 4: Docker¶

Run Victor in a container without installing Python dependencies:

# Pull the latest image
docker pull vjsingh1984/victor-ai:latest

# Run Victor interactively
docker run -it \
  -v ~/.victor:/root/.victor \
  -v "$(pwd)":/workspace \
  -w /workspace \
  vjsingh1984/victor-ai:latest chat

# With API keys
docker run -it \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -v ~/.victor:/root/.victor \
  -v "$(pwd)":/workspace \
  -w /workspace \
  vjsingh1984/victor-ai:latest chat

Docker Compose example:

# docker-compose.yml
version: '3.8'
services:
  victor:
    image: vjsingh1984/victor-ai:latest
    volumes:
      - ~/.victor:/root/.victor
      - .:/workspace
    working_dir: /workspace
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    stdin_open: true
    tty: true

Method 5: Development Installation¶

Follow the canonical development setup guide, which
installs the in-repository contracts package before Victor. Native extension
builds and contribution worktrees are documented there and in the
pull-request workflow.

Optional Dependencies¶

Victor has optional dependencies for specific features:

TUI dependency split on develop

After 0.12.0, develop moves Textual into the tui extra. For a source
checkout, follow the development setup above, then install pip install -e ".[tui]"
when using Textual interfaces. Published 0.12.0 still includes Textual in core.

Extra	Command	Features
api	`pip install victor-ai[api]`	FastAPI HTTP server, REST API
google	`pip install victor-ai[google]`	Google Gemini provider
checkpoints	`pip install victor-ai[checkpoints]`	SQLite checkpoint persistence for workflows
lang-all	`pip install victor-ai[lang-all]`	All tree-sitter language grammars
native	`pip install victor-ai[native]`	Maturin for Rust extensions
all	`pip install victor-ai[all]`	All optional dependencies

Install multiple extras:

pip install "victor-ai[api,google,checkpoints]"

Post-Installation Setup¶

Step 1: Initialize Victor¶

After installation, initialize Victor to create configuration files:

victor init

This creates:
- ~/.victor/profiles.yaml - Provider and model profiles
- ~/.victor/config.yaml - Global settings

Step 2: Verify Installation¶

Run these commands to verify Victor is working:

# Check version
victor --version

# List available providers
victor providers

# List available tools
victor tools

Expected output:

Victor AI v0.x.x
25 providers available
34 tools available

Step 3: Choose Your Model¶

Victor needs an LLM to function. You have two options:

Option A: Local Model (No API Key Required)¶

Ollama is the easiest way to run local models:

# Install Ollama
# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.com/install.sh | sh

# Start Ollama server
ollama serve

# In another terminal, pull a model
ollama pull qwen2.5-coder:7b

# Test with Victor
victor chat "Hello, Victor!"

Other local options:
- LM Studio: GUI-based, download from lmstudio.ai
- vLLM: High-throughput, requires GPU (pip install vllm)
- llama.cpp: CPU-friendly, minimal footprint

Option B: Cloud Provider (API Key Required)¶

Set up a cloud provider for more powerful models:

# Anthropic (Claude)
export ANTHROPIC_API_KEY=sk-ant-your-key-here
victor chat --provider anthropic "Hello, Victor!"

# OpenAI (GPT-4)
export OPENAI_API_KEY=sk-proj-your-key-here
victor chat --provider openai "Hello, Victor!"

# Google (Gemini)
export GOOGLE_API_KEY=your-key-here
victor chat --provider google "Hello, Victor!"

Secure key storage (recommended):

# Store in system keyring
victor keys --set anthropic --keyring
victor keys --set openai --keyring
victor keys --set google --keyring

Platform-Specific Instructions¶

Standalone binaries (no Python at all)¶

Prebuilt frozen binaries are published for macOS (arm64), Linux (x64 + arm64)
and Windows (x64) on each release's GitHub Releases page:

curl -fsSL -o victor.tar.gz \
  https://github.com/vijayksingh/victor/releases/latest/download/victor-linux-x64.tar.gz
tar -xzf victor.tar.gz && ./victor --version

Or use the installer, which picks the right artifact:
curl -fsSL <installer-url> | bash -s -- --binary. The uv/pipx methods
below remain the recommended CLI path (smaller updates, plugin ecosystem);
binaries are the no-Python fallback.

macOS¶

# Install Python 3.12+ if needed
brew install python@3.12

# Install pipx
brew install pipx
pipx ensurepath

# Install Victor
uv tool install --python 3.12 victor-ai   # or: pipx install --python python3.12 victor-ai

# Optional: Install Ollama for local models
brew install ollama

Linux (Ubuntu/Debian)¶

# Install Python 3.12+ if needed
sudo apt update
sudo apt install python3.12 python3.12-venv python3-pip

# Install pipx
python3.12 -m pip install --user pipx
python3.12 -m pipx ensurepath

# Restart terminal, then install Victor
uv tool install --python 3.12 victor-ai   # or: pipx install --python python3.12 victor-ai

# Optional: Install Ollama for local models
curl -fsSL https://ollama.com/install.sh | sh

Windows (WSL2)¶

Victor works best on Windows through WSL2:

# Install WSL2 (from PowerShell as Administrator)
wsl --install

# After restart, open Ubuntu terminal and update
sudo apt update && sudo apt upgrade

# Install Python and pipx
sudo apt install python3.12 python3.12-venv python3-pip
python3.12 -m pip install --user pipx
python3.12 -m pipx ensurepath

# Restart terminal, then install Victor
uv tool install --python 3.12 victor-ai   # or: pipx install --python python3.12 victor-ai

Troubleshooting¶

"command not found: victor"¶

Cause: Victor is not in your PATH.

Solutions:

If using pipx:

pipx ensurepath
source ~/.bashrc  # or ~/.zshrc

If using pip:

# Add pip user bin to PATH
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

"Package requires Python >= 3.12"¶

Cause: Your Python version is too old.

Solution:

# Check current version
python --version

# Install Python 3.12
# macOS: brew install python@3.12
# Ubuntu: sudo apt install python3.12

# Use specific version
python3.12 -m pip install victor-ai

"Could not build wheels"¶

Cause: Missing build tools.

Solutions:

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install build-essential python3-dev

# Then retry installation
pip install victor-ai

"Permission denied"¶

Cause: Trying to install globally without sudo.

Solution: Use pipx or a virtual environment (never use sudo with pip):

# Recommended
pipx install --python python3.12 victor-ai

# Alternative
python -m venv .venv
source .venv/bin/activate
pip install victor-ai

Ollama Connection Errors¶

Cause: Ollama server not running or wrong port.

Solutions:

# Start Ollama server
ollama serve

# Check if running
curl http://localhost:11434/api/version

# Pull a model if needed
ollama pull qwen2.5-coder:7b

# Set custom host if using non-default port
export OLLAMA_HOST=127.0.0.1:11434

Upgrading Victor¶

uv¶

uv tool upgrade victor-ai

pipx¶

pipx upgrade victor-ai

pip¶

pip install --upgrade victor-ai

Docker¶

docker pull vjsingh1984/victor-ai:latest

Development¶

git fetch origin
# Update your task branch using the pull-request workflow; do not switch the main checkout.
pip install -e ./victor-contracts -e ".[dev]"

Uninstalling Victor¶

uv¶

uv tool uninstall victor-ai

pipx¶

pipx uninstall victor-ai

pip¶

pip uninstall victor-ai

Docker¶

docker rmi vjsingh1984/victor-ai:latest

Remove configuration¶

rm -rf ~/.victor

Next Steps¶

After installation:

Quickstart - Run your first conversation
Configuration - Customize settings and profiles
User Guide - Learn daily usage patterns

Having issues? See the Troubleshooting Guide or open an issue.