Linux Deployment

Updated: 07/30/2026Word count: 0 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:

python3 --version
git --version

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

Ubuntu / Debian

sudo apt update && sudo apt install -y python3.12 python3-pip git

Fedora / RHEL

sudo dnf install -y python3.12 git

Arch Linux

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

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

Enter the folder and install dependencies:

uv sync

uv sync

pip install

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.