📦 MaiBot Installation Guide

Updated: 07/22/2026Word count: 0 wordsReading time: 1 min

Environment Requirements

• Python 3.12 or higher (Recommended: 3.12 / 3.13)
• Git

Download MaiBot

Download the latest version from GitHub Release, or clone the repository directly:

Stable Version (includes pre-release) (Recommended)

git clone https://github.com/Mai-with-u/MaiBot.git
cd MaiBot

Development Version (for early adopters)

git clone -b dev https://github.com/Mai-with-u/MaiBot.git
cd MaiBot

⚠️ Note

The dev branch has new features but may be unstable. It is recommended to choose the main branch for your first use.

Install Dependencies

We recommend using uv to manage dependencies.

Install uv

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS / Linux

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

Install Project Dependencies

Recommended: uv

uv sync

Fallback: pip (not recommended, may lack some dependencies)

pip install -r requirements.txt

Launch

Bash

uv run python bot.py

User Agreement Confirmation

The first launch will require you to accept the user agreement. It's simple:

Just type "agree" in the terminal!

Frequently Asked Questions

Why does it say "Model list cannot be empty" after launching?

The model_config.toml file must contain at least one model configuration. If automatic upgrade fails, you need to manually create a model configuration file, including:

• At least one API provider ([[api_providers]])
• At least one text model ([[models]])
• Corresponding task assignments ([model_task_config.xxx])

Vision models and embedding models are optional — configure vision models only when image viewing is needed, and configure embedding models only when memory functionality is enabled.

Refer to the Model Configuration Documentation for configuration.

uv command not found?

After installing uv, you need to add it to the PATH environment variable:

Bash

# Linux/macOS
source $HOME/.local/bin/env

# Or simply reopen the terminal

# Verify installation
uv --version

How to accept the user agreement in a non-interactive environment?

On a server or in a headless environment where you cannot type "agree" in the terminal, you can use environment variables to skip the prompt:

Bash

# Method 1: Use the hash value shown in the program prompt (may differ each time, refer to the actual prompt)
export EULA_AGREE=<hash_value_shown_in_terminal>
export PRIVACY_AGREE=<hash_value_shown_in_terminal>

# Method 2: Run once to see the required hash value, then start with environment variables
uv run python bot.py  # This will display the required environment variables