Install PocketPaw: pip, uv, Docker & One-Line Script

PocketPaw requires Python 3.11+ and can be installed via pip or uv.

Prerequisites

Python 3.11 or higher
pip, uv, or pipx package manager
An Anthropic API key (for cloud models) or Ollama (for local models — no API key needed)

Quick Install

The fastest way to get started — the interactive installer handles Python, uv, and feature selection:

curl -fsSL https://pocketpaw.xyz/install.sh | sh

Windows PowerShell Note

On Windows PowerShell, the above command will fail because sh is not recognized.

sh : The term 'sh' is not recognized as the name of a cmdlet...

Workarounds:

Use PowerShell-specific script (if available):

# Set execution policy to allow scripts
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

# Run PocketPaw installer
powershell -NoExit -Command "iwr -useb https://pocketpaw.xyz/install.ps1 | iex"

Use Git Bash or WSL to run the original Unix install script.

Or install directly with pip:

pip install pocketpaw

This installs the core package with minimal dependencies (~10 packages). To add specific features, use extras.

Using uv (Recommended)

uv is the recommended package manager for faster installs:

# Install uv if you haven't
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and install for development
git clone https://github.com/pocketpaw/pocketpaw.git
cd pocketpaw
uv sync --dev

# Run with auto-reload for development
uv run pocketpaw --dev

Package Extras

PocketPaw uses a modular extras system. Install only what you need:

Channel Extras

# Individual channels
pip install pocketpaw[telegram]
pip install pocketpaw[discord]
pip install pocketpaw[slack]
pip install pocketpaw[whatsapp-personal]  # QR-code pairing

# All channels
pip install pocketpaw[all-channels]

Tool Extras

# Specific tools
pip install pocketpaw[browser]    # Playwright browser automation
pip install pocketpaw[image]      # Google Gemini image generation
pip install pocketpaw[memory]     # Mem0 semantic memory

# All tools
pip install pocketpaw[all-tools]

Backend Extras

pip install pocketpaw[openai-agents]  # OpenAI Agents SDK backend
pip install pocketpaw[google-adk]     # Google ADK backend
pip install pocketpaw[desktop]        # Desktop automation tools

Composite Extras

# Recommended setup (dashboard + common tools)
pip install pocketpaw[recommended]

# Everything included
pip install pocketpaw[all]

# Development (includes test and lint tools)
pip install pocketpaw[dev]

Environment Variables

Set your API keys as environment variables. All PocketPaw settings use the POCKETPAW_ prefix:

# Option A: Anthropic API key for Claude (cloud)
export POCKETPAW_ANTHROPIC_API_KEY="sk-ant-..."

# Option B: Ollama for local models (no API key needed)
export POCKETPAW_LLM_PROVIDER="ollama"
export POCKETPAW_OLLAMA_MODEL="qwen2.5:7b"

# Optional: Other API keys
export POCKETPAW_OPENAI_API_KEY="sk-..."          # For voice/TTS/STT
export POCKETPAW_TAVILY_API_KEY="tvly-..."        # For web search
export POCKETPAW_GOOGLE_API_KEY="..."             # For image generation
export POCKETPAW_BRAVE_SEARCH_API_KEY="..."       # For Brave Search

Alternatively, you can configure these through the web dashboard’s settings panel.

Docker

For server deployments, PocketPaw includes a production-ready Dockerfile and docker-compose.yml:

git clone https://github.com/pocketpaw/pocketpaw.git
cd pocketpaw
cp .env.example .env    # fill in your API keys
docker compose up -d

The image includes all extras, Playwright Chromium, and OCR support. See the Docker deployment guide for optional Ollama/Qdrant services and configuration details.

Verify Installation

# Run PocketPaw (starts web dashboard)
pocketpaw

# Or with uv
uv run pocketpaw

The web dashboard will start at http://localhost:8888. Open it in your browser to verify everything is working.

Next Steps

Quick Start

Set up your first channel and send your first message.

Configuration

Learn about all configuration options.

Last updated: April 29, 2026

2 min read

Edit this page

Was this page helpful?