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

> Set up PraisonAI in your development environment

Install PraisonAI, set one provider key, and run an Agent in your own app.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(instructions="Be helpful")
agent.start("Summarise the top AI news today")
```

<RequestExample>
  ```bash Bot (gateway + channels) theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  pip install "praisonai-bot[gateway,bot]"
  ```

  ```bash Full (wrapper) theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  pip install praisonai
  ```

  ```bash Code (runtime) theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  pip install praisonai-code
  ```

  ```bash Agents (SDK) theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  pip install praisonaiagents
  ```

  ```bash npm theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  npm install praisonai
  ```

  ```bash One-Liner theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  curl -fsSL https://praison.ai/install.sh | bash
  ```
</RequestExample>

<Info>
  **Four packages, one ecosystem.** `pip install praisonai` pulls code, bot, and SDK. Lighter options below.
</Info>

<CardGroup cols={2}>
  <Card title="Terminal-only (smaller)" icon="terminal" href="/docs/features/praisonai-code-cli">
    `pip install praisonai-code` — agentic CLI without gateway or bots
  </Card>

  <Card title="Bots + gateway only" icon="comments" href="/docs/sdk/praisonai-bot/index">
    `pip install "praisonai-bot[gateway,bot]"` — channel runtime without the wrapper
  </Card>

  <Card title="Full (default)" icon="box" href="/docs/installation">
    `pip install praisonai` — wrapper, code, bot, and SDK together
  </Card>
</CardGroup>

<Note>
  `pip install praisonai` transitively installs `praisonai-code`, `praisonai-bot`, and `praisonaiagents`. You do not need to install them separately.
</Note>

# Installing PraisonAI

PraisonAI is published as **four** PyPI packages. Pick the one that matches what you want to do:

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Q1{What do I want to do?}:::agent

    Q1 -->|Full CLI with gateway,\nbots & integrations| P1[pip install praisonai]:::success
    Q1 -->|Gateway + bots only| P4["pip install praisonai-bot[gateway,bot]"]:::process
    Q1 -->|Run code-executing agents\nfrom the CLI, no wrapper| P2[pip install praisonai-code]:::process
    Q1 -->|Embed agents in\nmy own Python app| P3[pip install praisonaiagents]:::tool

    classDef agent fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef success fill:#10B981,stroke:#7C90A0,color:#fff
    classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
```

<Tabs>
  <Tab title="Full (praisonai)">
    The complete package — CLI, gateway, bots, integrations, YAML-driven multi-bot orchestration. Pulls `praisonai-code` and `praisonaiagents` automatically.

    <Note>
      For gateway hot reload (event-driven `gateway.yaml` watching via `watchdog`), install the gateway extra: `pip install "praisonai[gateway]"`.

      **`[claw]` extra:** `pip install "praisonai[claw]"` installs the full wrapper plus `praisonai-bot[gateway,bot]` — the WebSocket gateway and Telegram/Discord/Slack channel bots. Use this when you want the full wrapper and all channel runtime features in one command. For gateway + bots **without** the wrapper, use `pip install "praisonai-bot[gateway,bot]"` directly (see [Standalone Bot Gateway](/docs/features/standalone-bot-gateway)).
    </Note>

    <Steps>
      <Step title="Create Virtual Environment (Optional)">
        <CodeGroup>
          ```bash Mac/Linux theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
          python -m venv praisonai-env
          source praisonai-env/bin/activate
          ```

          ```bash Windows theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
          python -m venv praisonai-env
          .\praisonai-env\Scripts\activate
          ```
        </CodeGroup>
      </Step>

      <Step title="Install">
        ```bash Terminal theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        pip install praisonai
        ```
      </Step>

      <Step title="Configure Environment">
        Set your API key. PraisonAI auto-detects whichever provider credential is present:

        ```bash OpenAI theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        export OPENAI_API_KEY="${OPENAI_API_KEY:?Set OPENAI_API_KEY in your shell}"
        ```

        ```bash Anthropic theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        export ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY:?Set ANTHROPIC_API_KEY in your shell}"
        ```

        ```bash Gemini theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        export GEMINI_API_KEY="${GEMINI_API_KEY:?Set GEMINI_API_KEY in your shell}"
        ```

        ```bash Groq theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        export GROQ_API_KEY="${GROQ_API_KEY:?Set GROQ_API_KEY in your shell}"
        ```

        ```bash Ollama theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        export OLLAMA_HOST=http://localhost:11434
        ```

        <Note>
          If you only set `ANTHROPIC_API_KEY` (or `GEMINI_API_KEY`, `GOOGLE_API_KEY`, `GROQ_API_KEY`, `COHERE_API_KEY`, or `OLLAMA_HOST`), `praisonai run` picks the matching provider's default model automatically — no `--model` flag required. See [Provider Auto-Detection](/docs/models#provider-auto-detection-no-config-first-run) for the full lookup table.
        </Note>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Code (praisonai-code)">
    The standalone agent runtime — `run`, `chat`, `code`, and the full CLI backend, without the gateway/bot integrations. Depends only on `praisonaiagents`.

    <Steps>
      <Step title="Create Virtual Environment (Optional)">
        <CodeGroup>
          ```bash Mac/Linux theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
          python -m venv praisonai-env
          source praisonai-env/bin/activate
          ```

          ```bash Windows theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
          python -m venv praisonai-env
          .\praisonai-env\Scripts\activate
          ```
        </CodeGroup>
      </Step>

      <Step title="Install">
        ```bash Terminal theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        pip install praisonai-code
        ```
      </Step>

      <Step title="Configure Environment">
        ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        export OPENAI_API_KEY="${OPENAI_API_KEY:?Set OPENAI_API_KEY in your shell}"
        ```

        Any supported provider key works. See [Provider Auto-Detection](/docs/models#provider-auto-detection-no-config-first-run).
      </Step>

      <Step title="Run an agent">
        ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        from praisonaiagents import Agent

        agent = Agent(name="assistant", instructions="Be helpful")
        response = agent.start("Summarise the top AI news today")
        print(response)
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Bot (praisonai-bot)">
    Standalone bots and gateway — no full wrapper. Depends on `praisonaiagents` only at PyPI level.

    <Steps>
      <Step title="Install">
        ```bash Terminal theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        pip install "praisonai-bot[gateway,bot]"
        ```
      </Step>

      <Step title="Configure Environment">
        ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        export OPENAI_API_KEY="${OPENAI_API_KEY:?Set OPENAI_API_KEY in your shell}"
        export TELEGRAM_BOT_TOKEN="${TELEGRAM_BOT_TOKEN:?Set TELEGRAM_BOT_TOKEN in your shell}"
        ```
      </Step>

      <Step title="Start gateway">
        ```bash Terminal theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        praisonai-bot gateway start --host 127.0.0.1 --port 8765
        ```
      </Step>
    </Steps>

    See the [praisonai-bot SDK page](/docs/sdk/praisonai-bot/index) for Python API details.
  </Tab>

  <Tab title="Agents (SDK only)">
    The pure Python SDK — no CLI, no gateway, no heavy dependencies. Import directly in your own application.

    <Steps>
      <Step title="Create Virtual Environment (Optional)">
        <CodeGroup>
          ```bash Mac/Linux theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
          python -m venv praisonai-env
          source praisonai-env/bin/activate
          ```

          ```bash Windows theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
          python -m venv praisonai-env
          .\praisonai-env\Scripts\activate
          ```
        </CodeGroup>
      </Step>

      <Step title="Install">
        ```bash Terminal theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        pip install praisonaiagents
        ```
      </Step>

      <Step title="Configure Environment">
        ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        export OPENAI_API_KEY="${OPENAI_API_KEY:?Set OPENAI_API_KEY in your shell}"
        ```
      </Step>

      <Step title="Use in your app">
        ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        from praisonaiagents import Agent

        agent = Agent(name="assistant", instructions="Be helpful")
        response = agent.start("Hello!")
        print(response)
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="No Code">
    <Steps>
      <Step title="Create Virtual Environment (Optional)">
        <CodeGroup>
          ```bash Mac/Linux theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
          python -m venv praisonai-env
          source praisonai-env/bin/activate
          ```

          ```bash Windows theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
          python -m venv praisonai-env
          .\praisonai-env\Scripts\activate
          ```
        </CodeGroup>
      </Step>

      <Step title="Install PraisonAI">
        ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        pip install praisonai
        ```
      </Step>

      <Step title="Set API Key">
        Set your API key for the provider you want to use. PraisonAI auto-detects whichever credential is present:

        ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        export OPENAI_API_KEY="${OPENAI_API_KEY:?Set OPENAI_API_KEY in your shell}"
        ```

        Use Anthropic, Gemini, Groq, or Ollama instead? Just set that provider's key and `praisonai run` picks the right model automatically. See [Provider Auto-Detection](/docs/models#provider-auto-detection-no-config-first-run).
      </Step>
    </Steps>
  </Tab>

  <Tab title="JavaScript">
    <Steps>
      <Step title="Install PraisonAI">
        ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        npm install praisonai
        ```
      </Step>

      <Step title="Set API Key">
        ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        export OPENAI_API_KEY="${OPENAI_API_KEY:?Set OPENAI_API_KEY in your shell}"
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="TypeScript">
    <Steps>
      <Step title="Install PraisonAI">
        ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        npm install praisonai
        ```
      </Step>

      <Step title="Set API Key">
        ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        export OPENAI_API_KEY="${OPENAI_API_KEY:?Set OPENAI_API_KEY in your shell}"
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Note>
  All existing `praisonai` CLI verbs (`run`, `chat`, `code`, `gateway`, `bot`, …) continue to work unchanged — the wrapper routes them through the `praisonai-code` runtime. You do not need to change any scripts.
</Note>

## Package dependency chain

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    A[praisonaiagents\nCore SDK]:::tool --> B[praisonai-code\nRuntime + CLI]:::process
    B --> C[praisonai\nFull wrapper]:::success

    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef success fill:#10B981,stroke:#7C90A0,color:#fff
```

Each layer depends on the one to its left. Installing `praisonai` pulls all three; installing `praisonai-code` pulls only `praisonaiagents`; installing `praisonaiagents` has no PraisonAI dependencies.

Generate your OpenAI API key from [OpenAI](https://platform.openai.com/api-keys)
You can also use other LLM providers like Anthropic, Google, etc. Please refer to the [Models](/models) for more information.

## Which Install Do You Need?

<CardGroup cols={2}>
  <Card title="Terminal-only (smaller)" icon="terminal" href="/docs/features/praisonai-code-cli">
    `pip install praisonai-code` — agentic CLI: run, chat, code, runtime. No bots or gateway.
  </Card>

  <Card title="Full (default)" icon="package" href="/docs/installation">
    `pip install praisonai` — everything: bots, gateway, kanban, dashboard, and the agentic CLI.
  </Card>
</CardGroup>

<Note>
  `pip install praisonai` transitively installs `praisonai-code` and `praisonaiagents`. You do not need to install them separately.
</Note>

## How It Works

Pip installs the package, you export one provider key, and the CLI or SDK resolves the matching model at run time.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Installer as pip
    participant CLI as praisonai

    User->>Installer: pip install praisonai
    Installer-->>User: Package + dependencies installed
    User->>CLI: export PROVIDER_API_KEY && praisonai run
    CLI-->>User: Agent runs on the auto-selected model
```

## Best Practices

<AccordionGroup>
  <Accordion title="Install only what you need">
    Use `praisonaiagents` for a pure Python SDK, `praisonai-code` for the terminal runtime, and `praisonai` for the full wrapper with bots and gateway.
  </Accordion>

  <Accordion title="Use a virtual environment">
    Create a `venv` before installing to keep PraisonAI isolated from your system Python.
  </Accordion>

  <Accordion title="Export keys, don't hard-code them">
    Set `OPENAI_API_KEY` (or your provider's key) in your shell or `.env`. Never inline the raw value in code.
  </Accordion>

  <Accordion title="Skip --model on first runs">
    PraisonAI auto-detects the provider from whichever key is present and picks a sensible default model.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Quick Start" icon="bolt" href="/docs/quickstart">
    Build your first AI agent.
  </Card>

  <Card title="Models" icon="brain" href="/docs/models">
    Choose a provider and model.
  </Card>
</CardGroup>

***

## Quick Install

<Note>
  The one-liner installer uses an isolated backend (`uv tool` → `pipx` → venv fallback) and exposes `praisonai` via a `~/.local/bin/praisonai` shim — your global Python environment is untouched. See [Isolation Backends](/docs/install/isolation-backends) for details.
</Note>

<Tabs>
  <Tab title="macOS/Linux">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    curl -fsSL https://praison.ai/install.sh | bash
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    iwr -useb https://praison.ai/install.ps1 | iex
    ```

    <Note>
      **Windows terminals:** PraisonAI automatically detects legacy Windows code pages (CP1252, CP850, etc.) and falls back to ASCII-safe output. For full emoji and box-drawing rendering, switch your terminal to UTF-8:

      <CodeGroup>
        ```powershell PowerShell theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        $env:PYTHONIOENCODING='utf-8'
        chcp 65001
        ```

        ```cmd CMD theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        set PYTHONIOENCODING=utf-8
        chcp 65001
        ```
      </CodeGroup>
    </Note>
  </Tab>
</Tabs>

<Check>
  The installer automatically detects your OS, picks the best isolation backend (`uv tool` → `pipx` → venv fallback), installs Python if needed, and drops a `~/.local/bin/praisonai` shim on your PATH.
</Check>

<Note>
  **Requirements**

  * Python 3.10 or higher (auto-installed if missing)
  * macOS, Linux, or Windows
</Note>

***

## Package Structure

PraisonAI ships as three separate PyPI packages. Understanding which to install avoids surprises at runtime.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    A[pip install praisonai] --> B[praisonai wrapper]
    A --> C[praisonai-code CLI]
    A --> D[praisonaiagents SDK]
    E[pip install praisonai-code] --> C
    F[pip install praisonaiagents] --> D

    classDef full fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef code fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef sdk fill:#10B981,stroke:#7C90A0,color:#fff

    class A,B full
    class C,E code
    class D,F sdk
```

| Install command               | What you get                            | Agentic CLI (`run`, `chat`, `code`, …)                                                                           | Bot / gateway / pairing              |
| ----------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `pip install praisonai`       | Wrapper + code + agents                 | ✅ Full                                                                                                           | ✅ Yes                                |
| `pip install praisonai-code`  | Terminal-native agent CLI + LLM runtime | ✅ `run --output actions`, `daemon`, `doctor`, `config`, `version` — `chat`/`code`/default `run` need the wrapper | ❌ No — needs `pip install praisonai` |
| `pip install praisonaiagents` | Core SDK — Python API only              | ❌ No CLI                                                                                                         | N/A                                  |

<Note>
  **Standalone `pip install praisonai-code` supports the actions/daemon path as of PraisonAI 4.6.123+ (C7 + C9 four-tier).** Use `praisonai-code run --output actions "your prompt"` for the standalone in-process `Agent` path, and `praisonai-code daemon start --background` (spawns `python -m praisonai_code.runtime`) for the warm runtime. `run --help`, `config`, `doctor`, and `version` also work standalone.
</Note>

<Note>
  Default `run "prompt"`, `chat`, and `code` require the wrapper (`pip install praisonai`) and print a clear install hint if invoked standalone (for example, `Error: chat requires the praisonai wrapper. Install the full wrapper: pip install praisonai`). Wrapper-only features (`bot`, `claw`, `dashboard`, `gateway`, `identity`, `kanban`, `onboard`, `pairing`, framework adapters, YAML `--framework crewai/autogen`) also require `pip install praisonai` — they degrade gracefully rather than raising raw import errors. See [Standalone LLM Modules](/docs/features/standalone-llm-modules) and the [praisonai-code CLI](/docs/features/praisonai-code-cli).
</Note>

### PyPI publish order

Packages are published in dependency order:

```
1. praisonaiagents  →  2. praisonai-code  →  3. praisonai
```

If you pin versions, ensure all three packages resolve to the same release cycle.

Since 4.6.104, `praisonai` pins `praisonai-code>=0.0.2`, so `pip install praisonai` always pulls a compatible runtime automatically. See [`praisonaiagents` SDK page](/docs/api/praisonaiagents/index) for the release-cycle notes.