> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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

  ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  # 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
  ```
</Note>

<Note>
  **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)](/docs/features/lean-install-capabilities) for the exact coverage matrix and when to add `pip install litellm`.
</Note>

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "PraisonAI Extras"
        CORE[📦 Core Package]
        
        subgraph "Optional Extras"
            BOT[🤖 bot]
            API[🌐 api] 
            TOOLS[🔧 tools]
            STORAGE[💾 storage]
            FLOW[🎨 flow]
            ALL[⭐ all]
        end
        
        subgraph "Features Enabled"
            F1[Telegram, Discord, Slack]
            F2[Gateway, WebSocket, REST]
            F3[Web Search, File Processing]
            F4[Vector DBs, Cloud Storage]
            F6[Visual Workflow Builder + Langflow]
            F5[Everything Included]
        end
    end
    
    CORE --> BOT --> F1
    CORE --> API --> F2
    CORE --> TOOLS --> F3
    CORE --> STORAGE --> F4
    CORE --> FLOW --> F6
    CORE --> ALL --> F5
    
    classDef core fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef extra fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef feature fill:#10B981,stroke:#7C90A0,color:#fff
    
    class CORE core
    class BOT,API,TOOLS,STORAGE,FLOW,ALL extra
    class F1,F2,F3,F4,F5,F6 feature

```

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Feature as Installation Extras

    User->>Agent: Request
    Agent->>Feature: Process request
    Feature-->>Agent: Result    Agent-->>User: Response
```

## Quick Start

<Steps>
  <Step title="Choose Your Use Case">
    Select installation based on your requirements:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # 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]"
    ```

    <Note>
      `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.
    </Note>
  </Step>

  <Step title="Verify Installation">
    Test that required dependencies are available:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # 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
    ```
  </Step>

  <Step title="Handle Missing Dependencies">
    If you encounter import errors, install the required extra:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Error: Gateway requires starlette and uvicorn
    pip install "praisonai[api]"

    # Error: No module named 'python-telegram-bot'
    pip install "praisonai[bot]"
    ```
  </Step>
</Steps>

***

## Available Extras

### Bot Integration (`[bot]`)

Enables chat platform integrations:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:**

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:**

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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'`)

<Warning>
  **`[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.
</Warning>

<Note>
  **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.
</Note>

**Use cases:**

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

**Example:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai flow
# Opens http://localhost:7860 with Agent + Agent Team components
```

See [Flow CLI](/docs/cli/flow) and [Visual Workflow Builder](/docs/ui/flow).

### Training (`praisonai-train`)

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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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]"
```

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

| 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](/docs/features/praisonai-train-benchmark) 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](https://pytorch.org/get-started/locally/); 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](/docs/train#conda-setup-what-the-script-installs-on-your-machine) for the decision table.

See [Train](/docs/train) and [praisonai-train Package](/docs/features/praisonai-train-package).

### Complete Installation (`[all]`)

All optional dependencies included:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install "praisonai[bot,api]"
```

**Why both extras:**

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

**Configuration:**

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install praisonai
# No extras needed for core agent functionality
```

**Example:**

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

<AccordionGroup>
  <Accordion title="Gateway requires starlette and uvicorn">
    **Error:**

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    ImportError: Gateway requires starlette and uvicorn.
    Install with: pip install praisonai[api]
    ```

    **Solution:**

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install "praisonai[api]"
    # or
    pip install "praisonai[bot,api]" # for bot + gateway
    ```
  </Accordion>

  <Accordion title="No module named 'python-telegram-bot'">
    **Error:**

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    ModuleNotFoundError: No module named 'python-telegram-bot'
    ```

    **Solution:**

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install "praisonai[bot]"
    ```

    This happens when trying to use Telegram integration without the bot extra.
  </Accordion>

  <Accordion title="No module named 'chromadb'">
    **Error:**

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    ModuleNotFoundError: No module named 'chromadb'
    ```

    **Solution:**

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install "praisonai[storage]"
    # or
    pip install "praisonai[all]"
    ```

    Vector storage requires the storage extra.
  </Accordion>

  <Accordion title="Cannot install on Windows">
    **Symptoms:** Package installation fails on Windows

    **Solutions:**

    For encoding issues:

    ```powershell theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    $env:PYTHONUTF8 = "1"
    pip install "praisonai[bot,api]"
    ```

    For build errors:

    ```powershell theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Install Visual Studio Build Tools
    # or use conda-forge
    conda install -c conda-forge praisonai
    ```
  </Accordion>

  <Accordion title="Langflow is not installed">
    **Error:**

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

    **Solution:**

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install "praisonai[flow]"
    ```
  </Accordion>

  <Accordion title="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:**

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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).
  </Accordion>

  <Accordion title="ImportError: cannot import name 'EventSourceResponse' from 'fastapi.responses'">
    **Cause:** Old `fastapi-pagination<0.12.34` is installed against a newer FastAPI/Starlette.

    **Solution:**

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install --upgrade "praisonai[flow]"
    # or, manually:
    pip install "fastapi-pagination>=0.12.34"
    ```
  </Accordion>
</AccordionGroup>

### Dependency Conflicts

Handle version conflicts between extras:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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

<AccordionGroup>
  <Accordion title="Use virtual environments">
    Always isolate PraisonAI installations:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # 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]"
    ```
  </Accordion>

  <Accordion title="Pin versions in production">
    Use specific versions for reproducible builds:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # requirements.txt
    praisonai[bot,api]==1.2.3
    python-telegram-bot==20.7
    fastapi==0.104.1
    ```
  </Accordion>

  <Accordion title="Install only needed extras">
    Minimize dependency footprint:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Development: everything
    pip install "praisonai[all]"

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

    # Gateway only: minimal  
    pip install "praisonai[api]"
    ```
  </Accordion>

  <Accordion title="Monitor dependency security">
    Keep dependencies updated:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Check for vulnerabilities
    pip-audit

    # Update safely
    pip install --upgrade "praisonai[all]"
    pip check  # Verify no conflicts
    ```
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Gateway Overview" icon="broadcast-tower" href="/docs/features/gateway-overview">
    Gateway requires \[api] extra
  </Card>

  <Card title="Bot Integrations" icon="robot" href="/docs/features/bot-gateway">
    Bot platforms require \[bot] extra
  </Card>

  <Card title="praisonai-train Package" icon="graduation-cap" href="/docs/features/praisonai-train-package">
    Training ships in praisonai-train
  </Card>

  <Card title="Package Tiers" icon="layer-group" href="/docs/features/architecture-tiers">
    How the six packages stack
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.