Skip to content

🔧 Installation Guide

This guide covers installing SuperOptiX and the optional extras for each supported agent runtime.

🚀 Quick Start

New to SuperOptiX? Start with our Quick Start Guide after installation!

One-line install

The installer sets up uv if it is missing, then installs SuperOptiX into an isolated tool environment. It never uses sudo. 

curl -fsSL https://superoptix.ai/install.sh | sh

📋 Prerequisites

Required

  • Python 3.11+ (required)
  • Git (required for DSPy installation)
  • Package Manager (uv recommended, pip also supported)

Verify Requirements

# Check Python version
python --version  # Should be 3.11 or higher

# Check Git
git --version  # Should show git version

Install Git (if needed)

xcode-select --install

# Ubuntu/Debian
sudo apt-get install git

# CentOS/RHEL
sudo yum install git

Download from git-scm.com

Python Version Requirement

SuperOptiX requires Python 3.11 or higher. Check your version with: 

python --version

🎯 Installation Methods

Framework-Free Core

SuperOptiX core is now framework-independent! 🎉

Install only what you need. Choose from 6 AI frameworks, or use core without any.

One line

Installs uv when it is missing, then SuperOptiX into an isolated tool environment. Works on macOS, Linux and WSL, and never uses sudo.

curl -fsSL https://superoptix.ai/install.sh | sh

Extras and an exact version are selected with environment variables:

curl -fsSL https://superoptix.ai/install.sh | SUPEROPTIX_EXTRAS=a2a sh
curl -fsSL https://superoptix.ai/install.sh | SUPEROPTIX_VERSION=0.3.5 sh

With uv directly

If you already have uv and would rather run it yourself:

# Install uv if you do not have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install SuperOptiX into an isolated tool environment
uv tool install superoptix

# Verify
super --version

Add Framework Dependencies with uv Tool

Use --with to install framework dependencies in the same tool environment:

# OpenAI SDK support
uv tool install superoptix --with "superoptix[frameworks-openai]"

# Claude SDK support
uv tool install superoptix --with "superoptix[frameworks-claude-sdk]"

# Google ADK support
uv tool install superoptix --with "superoptix[frameworks-google]"

# Pydantic AI support
uv tool install superoptix --with "superoptix[frameworks-pydantic-ai]"

Upgrade later:

uv tool upgrade superoptix

Alternative: Using pip

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install SuperOptiX
uv pip install superoptix

📦 Optional Frameworks & Extras

Customize your installation by adding only what you need:

🌐 AI Frameworks

Framework Install Command Includes
DSPy ⭐ uv tool install superoptix --with "superoptix[frameworks-dspy]" DSPy + GEPA
OpenAI SDK uv tool install superoptix --with "superoptix[frameworks-openai]" openai-agents, openai SDK
Claude SDK uv tool install superoptix --with "superoptix[frameworks-claude-sdk]" claude-agent-sdk
Google ADK uv tool install superoptix --with "superoptix[frameworks-google]" google-adk, google-generativeai
Microsoft uv tool install superoptix --with "superoptix[frameworks-microsoft]" agent-framework>=1.16, azure-identity
DeepAgents uv tool install superoptix --with "superoptix[frameworks-deepagents]" deepagents
Pydantic AI uv tool install superoptix --with "superoptix[frameworks-pydantic-ai]" Pydantic AI
CrewAI ⚠️ uv tool install superoptix --with crewai==1.2.0 crewai (conflicts with DSPy)

⭐ Recommended: DSPy for GEPA optimization
⚠️ Note: CrewAI and DSPy cannot be installed together in the same environment.

🔌 Tool Optimization & MCP

uv tool install superoptix --with "superoptix[mcp]"

🧠 Vector Databases (RAG)

# All vector databases
uv tool install superoptix --with "superoptix[vectordb]"

# Or specific ones
uv tool install superoptix --with "superoptix[chromadb]"    # ChromaDB (recommended)
uv tool install superoptix --with "superoptix[qdrant]"      # Qdrant

🔍 Observability

uv tool install superoptix --with "superoptix[observability]"
Includes MLflow, Pandas, Plotly.

💻 Local Model Management

# Apple Silicon (MLX)
uv tool install superoptix --with "superoptix[mlx]"

# HuggingFace
uv tool install superoptix --with "superoptix[huggingface]"

🔍 Verification

After installation, verify SuperOptiX is working correctly:

# Check CLI
super --version

# Check available commands
super --help

🚀 Next Steps

  1. Set up your LLM: Follow our LLM Setup Guide
  2. Create your first agent: Try our Quick Start Guide
  3. Explore the framework: Check out our Agent Patterns

🆘 Troubleshooting

Common Issues

Import Error: Make sure you're using Python 3.11+ 

python --version

Package Not Found: Update pip/uv 

uv tool upgrade superoptix

CrewAI Installation Conflicts: If you encounter dependency conflicts when installing CrewAI with SuperOptiX: 

# The issue: CrewAI requires json-repair==0.25.2, but DSPy needs json-repair>=0.30.0
# Solution: Install manually with --no-deps flag
uv tool install superoptix --with "superoptix[frameworks-dspy]"  # Install DSPy support first
uv tool install superoptix --with crewai>=1.15  # Add CrewAI manually
uv tool install superoptix --with "json-repair>=0.30.0"  # Ensure compatible version

Still Having Issues?