Package Manager Deployment (uv)

Use uv to install and run AstrBot quickly.

Before You Start

If uv is not installed, install it first by following the official guide: https://docs.astral.sh/uv/

uv supports Linux, Windows, and macOS.

Important Notes

WARNING

AstrBot deployed via uv does not support upgrading through the WebUI. To update, run uv tool upgrade astrbot --python 3.12 from the command line.

AstrBot requires Python 3.12 or later. Use --python 3.12 to ensure that uv creates the tool environment with Python 3.12; if Python downloads are enabled, uv will download Python 3.12 automatically when it is missing.

Install and Start

uv tool install astrbot --python 3.12
astrbot init # Only required for the first deployment
astrbot run

Install as a System Service

After initialization, install AstrBot as a user-level service so it starts with the user session:

astrbot service install --now

The command uses the astrbot executable found on PATH (usually generated by uv tool install) and uses the current directory as the AstrBot working directory. Each platform uses its native user-level service mechanism:

• Linux: systemd --user
• macOS: LaunchAgent
• Windows: Task Scheduler

To specify the AstrBot working directory or executable path explicitly:

astrbot service install --workdir /path/to/astrbot-root --executable /path/to/astrbot --now

To inspect the service state and WebUI health:

astrbot service status

The status output includes the service manager state, AstrBot working directory, Dashboard port, WebUI URL, WebUI accessibility, and the overall health state.

You can also manage the service lifecycle with:

astrbot service start
astrbot service stop
astrbot service restart
astrbot service uninstall

To view service logs:

astrbot service logs
astrbot service logs -f

On macOS and Windows, this shows stdout logs by default. To include stderr:

astrbot service logs --include-stderr

To read the AstrBot application log file at data/logs/astrbot.log, enable application file logging first and restart the service:

astrbot service logs enable
astrbot service restart
astrbot service logs --source app

To inspect or disable application file logging:

astrbot service logs status
astrbot service logs disable