Installation Extras

Optional dependencies and feature packages for specialized PraisonAI functionality

PraisonAI provides optional dependency groups (extras) for specific features like bot integrations, gateway servers, and storage backends.

Package split. Framework integrations (CrewAI, AutoGen, AG2) are now distributed through a separate package:

# Native runtime (recommended)
pip install praisonaiagents

# Framework integrations (CrewAI, AutoGen, AG2)
pip install praisonai-frameworks[crewai]
pip install praisonai-frameworks[autogen]
pip install praisonai-frameworks[ag2]

# Legacy (deprecated) — still works but will be removed
# pip install 'praisonai[crewai]'  # use praisonai-frameworks[crewai] instead

Lean install without litellm? Capability detection (structured outputs, function calling, prompt caching, web search) still works via a built-in static heuristic. See Lean Install (litellm-free) for the exact coverage matrix and when to add pip install litellm.

from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful.")
agent.start("Hello!")

The user installs optional extras, then runs agents with the features those extras unlock.

​

How It Works

​

Quick Start

1. Choose Your Use Case

   Select installation based on your requirements:

   # Basic agent development
   pip install praisonai
   
   # Bot integrations (Telegram, Discord, Slack)
   pip install "praisonai[bot]"
   
   # Gateway server with WebSocket/REST
   pip install "praisonai[api]"
   
   # Visual workflow builder (Langflow)
   pip install "praisonai[flow]"
   
   # Gateway + bots (most common)
   pip install "praisonai[bot,api]"
   
   # Everything included
   pip install "praisonai[all]"
   

   praisonaiagents[all] also installs the [autonomy] and [os] optional groups (verification hooks, OS/gateway helpers). The wrapper extra praisonai[all] focuses on bots, gateway, and tools — add pip install "praisonaiagents[autonomy]" or "praisonaiagents[os]" when you need only those slices.

2. Verify Installation

   Test that required dependencies are available:

   # Test core functionality
   from praisonaiagents import Agent
   agent = Agent(name="test", instructions="Hello")
   
   # Test bot integration (if [bot] installed)
   from praisonai.bots import TelegramBot
   
   # Test gateway (if [api] installed)
   from praisonai.gateway import WebSocketGateway
   
3. Handle Missing Dependencies

   If you encounter import errors, install the required extra:

   # Error: Gateway requires starlette and uvicorn
   pip install "praisonai[api]"
   
   # Error: No module named 'python-telegram-bot'
   pip install "praisonai[bot]"
   

---

​

Available Extras

​

Bot Integration ([bot])

Enables chat platform integrations:

pip install "praisonai[bot]"

Includes:

• python-telegram-bot - Telegram bot API
• discord.py - Discord bot integration
• slack-sdk - Slack app development
• twilio - WhatsApp Business API
• requests - HTTP client for webhooks

Use cases:

• Telegram bot deployment
• Discord server integration
• Slack workspace apps
• WhatsApp Business messaging
• Multi-platform chat bots

Example:

from praisonai.bots import TelegramBot, DiscordBot

telegram = TelegramBot(token="your_token")
discord = DiscordBot(token="your_token")

​

API Server ([api])

Enables gateway and web server functionality:

pip install "praisonai[api]"

Includes:

• uvicorn - ASGI server
• fastapi - Web framework
• starlette - WebSocket support
• python-multipart - File upload handling
• websockets - WebSocket protocol

Use cases:

• PraisonAI Gateway deployment
• REST API endpoints
• WebSocket real-time communication
• Agent-as-a-Service hosting
• Dashboard and UI backends

Example:

from praisonai.gateway import WebSocketGateway
from praisonaiagents import GatewayConfig

config = GatewayConfig(host="127.0.0.1", port=8765)
gateway = WebSocketGateway(config=config)

​

Tools Collection ([tools])

Specialized tools and integrations:

pip install "praisonai[tools]"

Includes:

• tavily-python - Web search API
• requests - HTTP requests
• beautifulsoup4 - HTML parsing
• PyPDF2 - PDF processing
• python-docx - Word document handling

Use cases:

• Web search capabilities
• Document processing
• File format conversion
• Data extraction and parsing
• Research and analysis

​

Storage Backends ([storage])

Database and vector store integrations:

pip install "praisonai[storage]"

Includes:

• chromadb - Vector database
• qdrant-client - Qdrant vector store
• pinecone-client - Pinecone vector database
• redis - Redis caching
• pymongo - MongoDB integration

Use cases:

• Knowledge base storage
• Vector similarity search
• Session state persistence
• Caching and performance
• Multi-agent coordination

​

Visual Flow Builder ([flow])

Launch Langflow with PraisonAI Agent and AgentTeam components pre-loaded:

pip install "praisonai[flow]"

Includes:

• langflow>=1.0.0 — visual workflow builder
• requests>=2.31.0 — Langflow REST client
• a2a-sdk[http-server]>=1.0.0 — Langflow transitive dep pinned for Python 3.13 (older versions ship without a2a.server.active_task)
• fastapi-pagination>=0.12.34 — pinned for FastAPI/Starlette compatibility (older versions fail with cannot import name 'EventSourceResponse')

[flow] and [claw] are mutually exclusive. [flow] pins a2a-sdk[http-server]>=1.0.0 (required by Langflow), while [claw] — via praisonaiagents[a2ui] — pins a2a-sdk>=0.3.0,<1.0.0 (required by the Google A2UI SDK). Install these two heavy extras in separate virtual environments. pip install "praisonai[flow,claw]" or pip install "praisonai[all]" on top of [flow] will resolve to one version and break the other feature at runtime.

Python 3.13 is supported as of PraisonAI (post-#5103). First-boot on Windows takes ~5 minutes because Langflow builds its migration/cache database — this is Langflow behaviour, not a hang.

Use cases:

• Launch the Langflow UI with PraisonAI components in the sidebar
• Import/export YAML ↔ Langflow JSON
• Visual multi-agent workflow design

Example:

praisonai flow
# Opens http://localhost:7860 with Agent + Agent Team components

See Flow CLI and Visual Workflow Builder.

​

Training (praisonai-train)

LLM fine-tuning and iterative agent training ship in the standalone praisonai-train package (Tier 2c).

# Agent training only (lightweight — pulls praisonaiagents + litellm, no CUDA/Unsloth)
pip install praisonai-train

# Adds the Unsloth/torch stack for LLM fine-tuning
pip install "praisonai-train[llm]"

# Full wrapper plus fine-tuning deps
pip install "praisonai[train]"

pip install "praisonai[train]" previously installed nothing (empty extra). It now pulls praisonai-train[llm], so it installs the Unsloth stack.

Command	Gets you	When to use
pip install praisonai-train	praisonai-train agents/list/show/apply/benchmark, no CUDA/Unsloth; litellm included for LLM-as-Judge grading	Fastest way to try LLM-as-Judge / human-feedback agent training, or benchmark deployments before you fine-tune
pip install "praisonai-train[llm]"	Above + Unsloth/torch stack for praisonai-train llm	Fine-tuning a base model
pip install praisonai	Full stack: praisonai train ... routes through the code tier	Standard PraisonAI install
pip install "praisonai[train]"	Now equivalent to praisonai + praisonai-train[llm]	Full stack plus fine-tuning deps

The bundled setup_conda_env.sh (used by praisonai-train[llm]) now probes the host for a GPU before picking pytorch-cuda=12.4. Nvidia hosts get the CUDA build; AMD hosts get a WARNING pointing at the official PyTorch ROCm instructions; CPU-only Linux hosts get a WARNING that praisonai-train llm refuses to run on CPU (the env is still usable for dataset work and exports). See Train → Conda setup for the decision table.

See Train and praisonai-train Package.

​

Complete Installation ([all])

All optional dependencies included:

pip install "praisonai[all]"

Includes: All extras above plus additional integrations.

Best for:

• Development environments
• Full-featured deployments
• Experimenting with all features
• Production systems using multiple capabilities

---

​

Common Use Cases

​

Gateway Deployment

Requirement: Multi-channel bot gateway with WebSocket support

pip install "praisonai[bot,api]"

Why both extras:

• [bot] provides Telegram, Discord, Slack integration
• [api] provides gateway WebSocket server and REST endpoints

Configuration:

# gateway.yaml
gateway:
  host: "127.0.0.1"
  port: 8765

channels:
  telegram:
    platform: telegram
    token: ${TELEGRAM_BOT_TOKEN}

​

Agent Development

Requirement: Basic agent creation and testing

pip install praisonai
# No extras needed for core agent functionality

Example:

from praisonaiagents import Agent

agent = Agent(
    name="researcher", 
    instructions="Research topics thoroughly",
    model="gpt-4o-mini"
)

​

Production Bot

Requirement: Robust bot with search, storage, and monitoring

pip install "praisonai[all]"

Features enabled:

• Bot platform integration
• Web search and document processing
• Vector knowledge storage
• REST API for monitoring
• All available tools and integrations

---

​

Installation Troubleshooting

​

Common Import Errors

Installing crawl4ai alongside the wrapper extras? crawl4ai pulls in unclecode-litellm, a fork that overwrites files in the real litellm. See the get_env_int_in_range entry below if import litellm or any agent LLM call fails after installing crawl4ai.

Gateway requires starlette and uvicorn

Error:

ImportError: Gateway requires starlette and uvicorn.
Install with: pip install praisonai[api]

Solution:

pip install "praisonai[api]"
# or
pip install "praisonai[bot,api]" # for bot + gateway

No module named 'python-telegram-bot'

Error:

ModuleNotFoundError: No module named 'python-telegram-bot'

Solution:

pip install "praisonai[bot]"

This happens when trying to use Telegram integration without the bot extra.

No module named 'chromadb'

Error:

ModuleNotFoundError: No module named 'chromadb'

Solution:

pip install "praisonai[storage]"
# or
pip install "praisonai[all]"

Vector storage requires the storage extra.

Cannot install on Windows

Symptoms: Package installation fails on Windows

Solutions:

For encoding issues:

$env:PYTHONUTF8 = "1"
pip install "praisonai[bot,api]"

For build errors:

# Install Visual Studio Build Tools
# or use conda-forge
conda install -c conda-forge praisonai

Langflow is not installed

Error:

Langflow is not installed. Install with: pip install praisonai[flow]

Solution:

pip install "praisonai[flow]"

ModuleNotFoundError: No module named 'a2a.server.active_task'

Cause: Old a2a-sdk<1.0 (e.g. 0.3.26) is installed. Langflow ≥ 1.10.x imports a2a.server.active_task, which only exists on a2a-sdk>=1.0.

Solution:

pip install --upgrade "praisonai[flow]"
# or, manually:
pip install "a2a-sdk[http-server]>=1.0.0"

This is fixed automatically for fresh installs on PraisonAI ≥ (post-#5103) because the [flow] extra now pins a2a-sdk[http-server]>=1.0.0. It resurfaces only if another extra downgrades a2a-sdk (e.g. [claw] — see the mutual exclusivity warning above).

ImportError: cannot import name 'EventSourceResponse' from 'fastapi.responses'

Cause: Old fastapi-pagination<0.12.34 is installed against a newer FastAPI/Starlette.

Solution:

pip install --upgrade "praisonai[flow]"
# or, manually:
pip install "fastapi-pagination>=0.12.34"

ImportError: cannot import name 'get_env_int_in_range' from 'litellm.litellm_core_utils.env_utils'

Cause: crawl4ai (≥ 0.8.6) depends on unclecode-litellm, a fork of litellm that installs into the same litellm/ directory. With both installed, pip or uv leaves a mix of files from both versions, so imports touching a submodule only one version has fail (ImportError, AttributeError, or ModuleNotFoundError under litellm.*).

Diagnose:

python -m pip show unclecode-litellm >/dev/null 2>&1 && echo "unclecode-litellm present"
python -c "from litellm.litellm_core_utils.env_utils import get_env_int_in_range" || echo "litellm files clobbered"

Solution: reinstall litellm last so its own files win:

# pip
pip install --force-reinstall --no-deps "litellm==$(python -m pip show litellm | awk '/^Version:/{print $2}')"

# uv
uv pip install --reinstall --no-deps "litellm==$(uv pip show litellm | awk '/^Version:/{print $2}')"

python -c "import litellm"

Re-run this after any reinstall or upgrade of crawl4ai. Alternatively, keep crawl4ai and litellm-using features in separate virtual environments.

​

Dependency Conflicts

Handle version conflicts between extras:

# Clean installation
pip uninstall praisonai
pip cache purge

# Reinstall with specific extras
pip install "praisonai[bot,api]==latest"

# Check for conflicts
pip check

​

Minimal Installation

For resource-constrained environments:

# Core only (smallest footprint)
pip install praisonai --no-deps
pip install openai  # Manual essential deps

# Specific platform only
pip install "praisonai[bot]" --no-deps
pip install python-telegram-bot openai

---

​

Extra Dependency Reference

Complete dependency listing by extra:

Extra	Key Dependencies	Size	Use Case
[bot]	python-telegram-bot, discord.py, slack-sdk	~50MB	Chat platform integration
[api]	uvicorn, fastapi, starlette	~30MB	Web server and WebSocket
[tools]	tavily-python, beautifulsoup4, PyPDF2	~25MB	Document and web processing
[storage]	chromadb, qdrant-client, pymongo	~100MB	Databases and vector stores
[flow]	langflow, requests, a2a-sdk[http-server]>=1.0, fastapi-pagination>=0.12.34	~500MB	Visual workflow builder (Langflow)
praisonai-train	praisonaiagents, litellm	~5MB	Iterative agent training (no CUDA/Unsloth)
praisonai-train[llm]	unsloth, torch	~2GB	LLM fine-tuning via Unsloth
[all]	All of the above + additional	~200MB	Complete functionality

​

Platform-Specific Notes

Windows:

• Some packages may require Visual Studio Build Tools
• UTF-8 encoding setup recommended: $env:PYTHONUTF8 = "1"
• Consider using conda for complex dependencies

macOS:

• May require Xcode Command Line Tools
• Install via Homebrew Python for best compatibility

Linux:

• Usually installs without issues
• May need system packages for some features (e.g., libssl-dev)

---

​

Best Practices

Use virtual environments

Always isolate PraisonAI installations:

# Create dedicated environment
python -m venv praisonai-env
source praisonai-env/bin/activate  # Linux/macOS
# or
praisonai-env\Scripts\activate     # Windows

# Install with extras
pip install "praisonai[bot,api]"

Pin versions in production

Use specific versions for reproducible builds:

# requirements.txt
praisonai[bot,api]==1.2.3
python-telegram-bot==20.7
fastapi==0.104.1

Install only needed extras

Minimize dependency footprint:

# Development: everything
pip install "praisonai[all]"

# Production bot: minimal
pip install "praisonai[bot]"

# Gateway only: minimal  
pip install "praisonai[api]"

Monitor dependency security

Keep dependencies updated:

# Check for vulnerabilities
pip-audit

# Update safely
pip install --upgrade "praisonai[all]"
pip check  # Verify no conflicts

---

​

Related

Gateway Overview

Gateway requires [api] extra

Bot Integrations

Bot platforms require [bot] extra

praisonai-train Package

Training ships in praisonai-train

Package Tiers

How the six packages stack