MaiBot Docs

English

简体中文

English

简体中文

Appearance

Linux Deployment ​

Updated: 09/14/2026Word count: 365 wordsReading time: 1 min

The most direct way to run MaiBot on Linux is source deployment. This guide covers most mainstream distributions, and macOS users can follow along too. If you'd rather not deal with Python environments, you can also use Docker Deployment.

Prepare the Environment ​

MaiBot needs Python 3.12, Git, and at least 2GB of available memory.

First, verify your environment:

bash
python3 --version
git --version

If the versions don't meet the requirements, install them for your distribution:

bash
sudo apt update && sudo apt install -y python3.12 python3-pip git
bash
sudo dnf install -y python3.12 git
bash
sudo pacman -S python git

TIP

MaiBot requires Python 3.12 or higher. If your system ships an older version, upgrade using pyenv or the latest package provided by your distribution.

Source Deployment ​

Install uv ​

We recommend using uv to manage dependencies. It's much faster than traditional pip.

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

TIP

If your terminal says uv: command not found after installation, run source $HOME/.local/bin/env to refresh environment variables, or simply open a new terminal window.

Download MaiBot ​

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

Enter the folder and install dependencies:

bash
uv sync
bash
pip install -r requirements.txt

Start ​

bash
uv run bot.py

On first launch, a user agreement prompt will appear. Type 同意 (agree) in the terminal to continue.

Accessing WebUI ​

After starting, MaiBot automatically launches the WebUI service. Open your browser and visit the following address (replace 本机IP with your server address; use localhost if running locally):

http://本机IP:8001

On first launch, the terminal will print the WebUI login Token, like this:

07-30 18:53:45 [WebUI] WebUI 配置文件不存在，正在创建: /MaiMBot/data/webui.json
07-30 18:53:45 [WebUI] WebUI 配置已保存到: /MaiMBot/data/webui.json
07-30 18:53:45 [WebUI] 新的 WebUI Token 已生成: QSwgc2Vu...
07-30 18:53:45 [WebUI应用] 🔑 WebUI 登录 Token: QSwgc2VucGFp77yBQ2lhbGxv772eKOKIoOODu8+JPCAp4oyS4piF
07-30 18:53:45 [WebUI应用] 💡 请使用此 Token 登录 WebUI
07-30 18:53:45 [WebUI服务] 🌐 WebUI 服务器启动中...

Copy the Token from the log and paste it into the browser login page to access WebUI. You can later view or modify the Token in data/webui.json.

Once in WebUI, follow the configuration wizard to set up models and connect platforms.

For the next steps on configuring models and connecting to QQ, refer to Model Configuration and Adapters.

Verification & Troubleshooting ​

Verify: after startup the terminal prints "WebUI 服务器启动中" (WebUI server starting), and curl -I http://127.0.0.1:8001 returns 200 or 307 — the service is ready.

uv: command not found?

  • Run source $HOME/.local/bin/env to refresh the environment, or reopen the terminal

pip install fails to compile?

  • On Ubuntu / Debian, install build dependencies first: sudo apt install -y build-essential python3.12-dev
  • Then rerun the install command

Python version below 3.12?

  • Upgrade to 3.12+ via your distro packages or pyenv, confirm with python3 --version, then install dependencies

Works locally but not from outside?

  • Check whether the cloud security group / firewall allows port 8001 (e.g. sudo ufw allow 8001)

Process gets Killed?

  • With less than 2GB of memory the OOM killer may terminate it; add memory or configure swap and retry