<!-- source: https://deepwiki.com/MervinPraison/PraisonAI/1.3-installation -->

# Installation

- .gitignore
- README.md
- src/praisonai/README.md

This document provides comprehensive installation instructions for PraisonAI, covering multiple installation methods and system configurations. For architecture details about the two-package system design, see [Architecture Overview](/MervinPraison/PraisonAI/1.1-architecture-overview). For initial configuration after installation, see [Configuration System](/MervinPraison/PraisonAI/8-configuration-system).

## Overview

PraisonAI offers four primary installation methods:

1. pip installation - Standard Python package installation with optional feature sets
2. Docker deployment - Containerized services for production and development
3. Homebrew - macOS package manager installation
4. Source installation - Building from the GitHub repository

The framework consists of two Python packages:

- praisonaiagents - Core agent framework (required)
- praisonai - Application layer with CLI, UI, and deployment tools (depends on praisonaiagents)

## Installation Methods Decision Tree

```

```

**Sources:** [src/praisonai/pyproject.toml1-121](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/pyproject.toml#L1-L121) [docker/README.md1-264](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/README.md?plain=1#L1-L264)

## Method 1: pip Installation

### Basic Installation

The minimal installation provides CLI functionality and core agent capabilities:

```

```

This installs `praisonai` (application layer) and automatically installs `praisonaiagents` (core framework) as a dependency.

**Installed components:**

- CLI with 50+ commands ( src/praisonai/praisonai/cli/main.py 1-2000 )
- Agent orchestration framework
- LLM integration via LiteLLM
- Task execution system
- Basic memory and tools

### Optional Feature Sets

PraisonAI uses Python's optional dependencies syntax to provide feature-specific installations:

**Sources:** [src/praisonai/pyproject.toml29-106](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/pyproject.toml#L29-L106)

### Core Agents Package Optional Features

For direct `praisonaiagents` installation with optional features:

**Sources:** [src/praisonai-agents/pyproject.toml22-90](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/pyproject.toml#L22-L90)

### Combined Installation

For a full-featured installation with all capabilities:

```

```

### System Requirements

- Python: >=3.10 (specified in both src/praisonai/pyproject.toml 7 and src/praisonai-agents/pyproject.toml 10 )
- Operating System: Linux, macOS, Windows
- Memory: Minimum 2GB RAM (4GB+ recommended for UI features)
- Disk Space: ~500MB for base installation, ~2GB with all features

## Method 2: Docker Installation

Docker provides pre-configured containerized environments with all dependencies installed.

### Package Architecture in Docker Context

```

```

**Sources:** [docker/Dockerfile.ui1-47](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.ui#L1-L47) [docker/Dockerfile.chat1-47](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.chat#L1-L47) [docker/Dockerfile1-47](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile#L1-L47) [docker/Dockerfile.dev1-47](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.dev#L1-L47)

### Single Container Deployment

#### UI Service (Chainlit Interface)

```

```

Access at: `http://localhost:8082`

**Configuration:**

- Base image: python:3.11-slim ( docker/Dockerfile.ui 1 )
- Installed packages: praisonai>=3.10.27 , praisonai[ui] , praisonai[crewai] ( docker/Dockerfile.ui 17-21 )
- Entry point: praisonai ui ( docker/Dockerfile.ui 33 )
- Config directory: /root/.praison ( docker/Dockerfile.ui 27-29 )

#### Chat Service (Enhanced Chat Interface)

```

```

Access at: `http://localhost:8083`

**Configuration:**

- Installed packages: praisonai[chat] , embedchain[github,youtube] ( docker/Dockerfile.chat 17-21 )
- Entry point: praisonai chat ( docker/Dockerfile.chat 33 )
- Includes: Web search (Tavily), web crawling (Crawl4AI), Playwright browser automation

#### API Service (REST Endpoints)

```

```

Access at: `http://localhost:8080`

**Configuration:**

- Installed packages: flask , praisonai[api] , gunicorn , markdown ( docker/Dockerfile 18-23 )
- Entry point: gunicorn -b 0.0.0.0:8080 api:app ( docker/Dockerfile 46 )
- Health check endpoint: /health ( docker/Dockerfile 33-43 )

#### Development Environment

```

```

**Configuration:**

- Additional tools: jupyter , jupyterlab , pytest , mkdocs , mkdocs-material ( docker/Dockerfile.dev 29-35 )
- Installed extras: praisonai[ui] , praisonai[chat] , praisonai[realtime] , praisonai[code] ( docker/Dockerfile.dev 22-27 )
- System packages: gcc , python3-dev , portaudio19-dev , git , vim , nano ( docker/Dockerfile.dev 6-15 )

**Sources:** [docker/Dockerfile.ui1-47](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.ui#L1-L47) [docker/Dockerfile.chat1-47](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.chat#L1-L47) [docker/Dockerfile1-47](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile#L1-L47) [docker/Dockerfile.dev1-47](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.dev#L1-L47)

### Multi-Service Deployment with Docker Compose

Create a `docker-compose.yml` file for orchestrating multiple services:

```

```

Create an environment file (`.env`):

```

```

Start all services:

```

```

Verify services are running:

```

```

**Sources:** [docker/README.md36-51](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/README.md?plain=1#L36-L51) [docker/README.md76-99](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/README.md?plain=1#L76-L99)

### Docker Configuration Directory Structure

```

```

The Docker setup consolidates all configuration and runtime files into a single directory (`/root/.praison` inside containers, mounted from `~/.praison` on the host). This design prevents file clutter in the root directory and enables persistent data across container restarts.

**Environment variables set in Docker images:**

- PRAISON_CONFIG_DIR=/root/.praison - Main configuration directory ( docker/Dockerfile.ui 27 )
- CHAINLIT_CONFIG_DIR=/root/.praison - Chainlit configuration location ( docker/Dockerfile.ui 28 )
- CHAINLIT_DB_DIR=/root/.praison - Database file location ( docker/Dockerfile.ui 29 )
- DOCKER_CONTAINER=true - Flag indicating containerized environment ( docker/Dockerfile.ui 30 )

**Sources:** [docker/Dockerfile.ui27-30](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.ui#L27-L30) [docker/README.md53-74](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/README.md?plain=1#L53-L74)

## Method 3: Homebrew Installation (macOS)

For macOS users, PraisonAI can be installed via Homebrew:

```

```

**Package details:**

- Formula: src/praisonai/praisonai.rb 1-20
- Version: 3.10.27 ( src/praisonai/praisonai.rb 6 )
- Python dependency: python@3.11 ( src/praisonai/praisonai.rb 10 )
- Source: GitHub releases tarball ( src/praisonai/praisonai.rb 6-7 )
- Installation method: Virtualenv with dependencies ( src/praisonai/praisonai.rb 13 )

Verify installation:

```

```

**Sources:** [src/praisonai/praisonai.rb1-20](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai.rb#L1-L20)

## Method 4: Installation from Source

For development, contributions, or using the latest unreleased features:

### Clone Repository

```

```

### Install Core Agents Package (Development Mode)

```

```

This installs `praisonaiagents` in editable mode, allowing you to modify the source code and see changes immediately.

**Package structure:**

- Build system: setuptools ( src/praisonai-agents/pyproject.toml 1-3 )
- Package location: src/praisonai-agents/praisonaiagents/
- Dependencies: pydantic>=2.10.0, rich, openai>=2.0.0, posthog>=3.0.0, aiohttp>=3.8.0 ( src/praisonai-agents/pyproject.toml 14-20 )

### Install Application Package (Development Mode)

```

```

This installs `praisonai` in editable mode with the CLI command available.

**Package structure:**

- Build system: setuptools>=64 ( src/praisonai/pyproject.toml 112 )
- Package location: src/praisonai/praisonai/
- Entry points: praisonai , setup-conda-env , praisonai-call ( src/praisonai/pyproject.toml 24-27 )
- Dependencies: rich>=13.7, markdown>=3.5, praisonaiagents>=0.13.23, litellm>=1.81.0, typer>=0.9.0, textual>=0.47.0 ( src/praisonai/pyproject.toml 11-22 )

### Install Optional Feature Sets for Development

```

```

### Verify Development Installation

```

```

**Sources:** [src/praisonai-agents/pyproject.toml1-95](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/pyproject.toml#L1-L95) [src/praisonai/pyproject.toml1-121](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/pyproject.toml#L1-L121)

## Configuration Directories

PraisonAI uses a centralized configuration directory to store runtime files, databases, and configuration data.

### Default Configuration Directory

- Location: ~/.praison (user home directory)
- Environment Variable: PRAISON_CONFIG_DIR

### Directory Structure After First Run

```
~/.praison/
|-- agents.yaml              # Agent configuration files
|-- config/                  # Additional configuration
|-- database.sqlite          # Chainlit conversation database
|-- chainlit.md             # Chainlit welcome page
|-- .chainlit/              # Chainlit runtime files
|   |-- config.toml
|   `-- translations/
|-- .files/                 # Uploaded files storage
`-- public/                 # Static web assets
```

### Configuration Directory in Different Installation Methods

### Customizing Configuration Directory

```

```

**Docker environment variables:**

- PRAISON_CONFIG_DIR - Main configuration directory ( docker/Dockerfile.ui 27 )
- CHAINLIT_CONFIG_DIR - Chainlit-specific configuration ( docker/Dockerfile.ui 28 )
- CHAINLIT_DB_DIR - Database file location ( docker/Dockerfile.ui 29 )

**Sources:** [docker/Dockerfile.ui27-30](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.ui#L27-L30) [docker/README.md53-74](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/README.md?plain=1#L53-L74) [src/praisonai/praisonai/cli/main.py108-116](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/cli/main.py#L108-L116)

## Post-Installation Verification

### Verify Installation

```

```

### Test CLI Commands

```

```

### Verify Docker Installation

```

```

### Verify Package Imports

```

```

**Sources:** [src/praisonai/praisonai/version.py1](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/version.py#L1-L1) [src/praisonai/praisonai/cli/main.py289-309](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/cli/main.py#L289-L309)

## Common Installation Issues

### Issue: Module Not Found

**Symptom:** `ModuleNotFoundError: No module named 'praisonai'`

**Solutions:**

```

```

### Issue: Port Already in Use (Docker)

**Symptom:** `Error starting userland proxy: listen tcp 0.0.0.0:8082: bind: address already in use`

**Solutions:**

```

```

### Issue: Permission Denied (Configuration Directory)

**Symptom:** `PermissionError: [Errno 13] Permission denied: '/root/.praison'`

**Solutions:**

```

```

### Issue: Missing Optional Dependencies

**Symptom:** `ImportError: No module named 'chainlit'` when running `praisonai ui`

**Solution:**

```

```

**Sources:** [docker/README.md168-206](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/README.md?plain=1#L168-L206) [src/praisonai/pyproject.toml29-106](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/pyproject.toml#L29-L106)

## Next Steps

After successful installation:

1. Configure API keys and environment variables - See Environment Variables
2. Create your first agent - See Agent Class
3. Explore CLI commands - See CLI Interface
4. Set up web UI - See Web UI (Chainlit)
5. Deploy to production - See Deployment and Infrastructure

**Sources:** [src/praisonai/pyproject.toml1-121](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/pyproject.toml#L1-L121) [src/praisonai-agents/pyproject.toml1-95](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/pyproject.toml#L1-L95) [docker/README.md1-264](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/README.md?plain=1#L1-L264) [src/praisonai/praisonai.rb1-20](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai.rb#L1-L20)
