Installation

System Requirements

Before installing nanobot, ensure your system meets these requirements:

Python Version

Python ≥3.11 requiredCheck your version:

python --version

Optional Dependencies

Node.js ≥18 (for WhatsApp integration)
Docker (for containerized deployment)
Matrix support (install with pip install nanobot-ai[matrix])

Python 3.10 and earlier are not supported. nanobot requires Python 3.11 or newer for optimal performance and modern language features.

Installation Methods

Choose the installation method that best fits your use case:

pip (Stable)
uv (Fast)
Source (Latest)
Docker

Install from PyPI

The simplest way to install nanobot is via pip:

pip install nanobot-ai

This installs the latest stable release from PyPI.

Use a virtual environment to avoid conflicts with other Python packages:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install nanobot-ai

Verify installation:

nanobot --version

You should see output like:

🐈 nanobot v0.1.4.post3

Install with uv

uv is a fast Python package installer written in Rust. It’s significantly faster than pip:

uv tool install nanobot-ai

Benefits of uv:

10-100x faster than pip
Automatic virtual environment management
Better dependency resolution

If you don’t have uv installed:

curl -LsSf https://astral.sh/uv/install.sh | sh

Verify installation:

nanobot --version

Install from Source

Get the latest features and bug fixes by installing directly from the GitHub repository:

git clone https://github.com/HKUDS/nanobot.git
cd nanobot
pip install -e .

The -e flag installs in editable mode, meaning:

Changes to the source code take effect immediately
Perfect for development and experimentation
You can easily pull updates with git pull

Verify installation:

nanobot --version

For contributors: Install development dependencies:

pip install -e ".[dev]"

This includes pytest, ruff, and other dev tools.

Docker Installation

Run nanobot in an isolated container without installing Python locally.Prerequisites:

Docker installed (Get Docker)

Using Docker Compose (Recommended)

git clone https://github.com/HKUDS/nanobot.git
cd nanobot

# First-time setup
docker compose run --rm nanobot-cli onboard

# Edit config (add your API keys)
vim ~/.nanobot/config.json

# Start gateway
docker compose up -d nanobot-gateway

# View logs
docker compose logs -f nanobot-gateway

Using Docker Directly

# Build the image
docker build -t nanobot .

# Initialize config
docker run -v ~/.nanobot:/root/.nanobot --rm nanobot onboard

# Edit config on host
vim ~/.nanobot/config.json

# Run gateway
docker run -v ~/.nanobot:/root/.nanobot -p 18790:18790 nanobot gateway

# Or run a single command
docker run -v ~/.nanobot:/root/.nanobot --rm nanobot agent -m "Hello!"

The -v ~/.nanobot:/root/.nanobot flag mounts your local config directory into the container, so your configuration and workspace persist across container restarts.

Docker Compose Commands:

# Start services
docker compose up -d nanobot-gateway

# Stop services
docker compose down

# View logs
docker compose logs -f nanobot-gateway

# Run CLI command
docker compose run --rm nanobot-cli agent -m "Hello!"

# Restart after config changes
docker compose restart nanobot-gateway

Platform-Specific Instructions

macOS

macOS Installation

Install Python 3.11+ via Homebrew:

brew install [email protected]

Install nanobot:

pip3 install nanobot-ai
# or
uv tool install nanobot-ai

For WhatsApp support (requires Node.js):

brew install node

macOS includes Python 2.7 by default. Make sure you’re using Python 3.11+ with python3 --version.

Linux (Ubuntu/Debian)

Ubuntu/Debian Installation

Install Python 3.11+ and pip:

sudo apt update
sudo apt install python3.11 python3.11-venv python3-pip

Install nanobot:

pip install nanobot-ai
# or
uv tool install nanobot-ai

For WhatsApp support:

# Install Node.js 18+
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

On some distributions, you may need to use pip3 instead of pip and python3 instead of python.

Linux (Fedora/RHEL)

Fedora/RHEL Installation

Install Python 3.11+ and pip:

sudo dnf install python3.11 python3-pip

Install nanobot:

pip install nanobot-ai
# or
uv tool install nanobot-ai

For WhatsApp support:

sudo dnf install nodejs npm

Windows

Windows Installation

Install Python 3.11+ from python.orgDuring installation:

✅ Check “Add Python to PATH”
✅ Check “Install pip”

Install nanobot via PowerShell or Command Prompt:

pip install nanobot-ai

For WhatsApp support, install Node.js from nodejs.org

Windows paths with spaces may cause issues. Use quotes when specifying paths:

nanobot agent --workspace "C:\Users\Your Name\.nanobot\workspace"

Optional Dependencies

Matrix/Element Support

For Matrix (Element) channel integration with end-to-end encryption:

pip install nanobot-ai[matrix]

This installs:

matrix-nio[e2e] - Matrix client with E2EE support
mistune - Markdown parsing
nh3 - HTML sanitization

Development Dependencies

For contributing to nanobot or running tests:

pip install nanobot-ai[dev]

This includes:

pytest and pytest-asyncio - Testing framework
ruff - Fast Python linter and formatter
All Matrix dependencies

Verification Steps

After installation, verify everything is working:

Check version

nanobot --version

Expected output:

🐈 nanobot v0.1.4.post3

Initialize configuration

nanobot onboard

This creates:

~/.nanobot/config.json - Configuration file
~/.nanobot/workspace/ - Working directory
~/.nanobot/workspace/MEMORY.md - Persistent memory
~/.nanobot/workspace/HEARTBEAT.md - Periodic tasks

Check status

nanobot status

You should see:

🐈 nanobot Status

Config: /home/user/.nanobot/config.json ✓
Workspace: /home/user/.nanobot/workspace ✓
Model: anthropic/claude-opus-4-5
OpenRouter: not set

Configuration is empty by default. You’ll need to add your API keys before using nanobot. See the Quick Start guide for next steps.

Troubleshooting

Command not found: nanobot

Issue: Shell can’t find the nanobot command after installation.Solutions:

Check if Python scripts directory is in PATH:

# Linux/macOS
echo $PATH | grep -o "[^:]*python[^:]*"

# Windows PowerShell
$env:PATH -split ';' | Select-String python

Find where pip installed nanobot:
```
pip show nanobot-ai | grep Location
```

Add to PATH (Linux/macOS):

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

Use Python module directly (temporary workaround):
```
python -m nanobot.cli.commands --version
```

ModuleNotFoundError: No module named 'nanobot'

Issue: Python can’t find the nanobot module.Solutions:

Verify installation:
```
pip list | grep nanobot
```

Reinstall nanobot:

pip uninstall nanobot-ai
pip install nanobot-ai

Check Python version:
```
python --version  # Must be 3.11+
```

Use virtual environment:

python -m venv venv
source venv/bin/activate
pip install nanobot-ai

Permission denied errors

Issue: Permission errors during installation.Solutions:

Install to user directory (recommended):
```
pip install --user nanobot-ai
```

Use virtual environment (best practice):

python -m venv venv
source venv/bin/activate
pip install nanobot-ai

Use sudo (not recommended):
```
sudo pip install nanobot-ai
```

Avoid using sudo pip install as it can cause conflicts with system packages. Use virtual environments instead.

Docker: Container exits immediately

Issue: Docker container starts but exits right away.Solutions:

Check logs:
```
docker compose logs nanobot-gateway
```
Verify config exists:
```
ls -la ~/.nanobot/config.json
```

Check API keys are set:

cat ~/.nanobot/config.json | grep apiKey

Run in foreground for debugging:
```
docker compose up nanobot-gateway
```

Next Steps

Once installation is complete:

Quick Start

Configure your first API key and start chatting

Configuration

Learn about providers, channels, and tools

Chat Channels

Connect Telegram, Discord, WhatsApp, and more

GitHub Issues

Get help or report installation problems

Pro tip: Bookmark the GitHub releases page to stay updated on new features and bug fixes.

Get Started

Core Concepts

Configuration

Chat Channels

Deployment

Advanced

System Requirements

Python Version

Optional Dependencies

Installation Methods

Install from PyPI

Install with uv

Install from Source

Docker Installation

Using Docker Compose (Recommended)

Using Docker Directly

Platform-Specific Instructions

macOS Installation

Ubuntu/Debian Installation

Fedora/RHEL Installation

Windows Installation

Optional Dependencies

Matrix/Element Support

Development Dependencies

Verification Steps

Troubleshooting

Next Steps

Quick Start

Configuration

Chat Channels

GitHub Issues

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Chat Channels

Deployment

Advanced

​System Requirements

Python Version

Optional Dependencies

​Installation Methods

​Install from PyPI

​Install with uv

​Install from Source

​Docker Installation

​Using Docker Compose (Recommended)

​Using Docker Directly

​Platform-Specific Instructions

​macOS Installation

​Ubuntu/Debian Installation

​Fedora/RHEL Installation

​Windows Installation

​Optional Dependencies

​Matrix/Element Support

​Development Dependencies

​Verification Steps

​Troubleshooting

​Next Steps

Quick Start

Configuration

Chat Channels

GitHub Issues

Build docs developers (and LLMs) love

System Requirements

Installation Methods

Install from PyPI

Install with uv

Install from Source

Docker Installation

Using Docker Compose (Recommended)

Using Docker Directly

Platform-Specific Instructions

macOS Installation

Ubuntu/Debian Installation

Fedora/RHEL Installation

Windows Installation

Optional Dependencies

Matrix/Element Support

Development Dependencies

Verification Steps

Troubleshooting

Next Steps