nonebot2

library2.5.0pypypi✓ verified 83d ago

NoneBot2 is an asynchronous, cross-platform Python bot framework that supports multiple adapters (e.g., OneBot, Telegram, Discord). It uses a plugin system and is built on asyncio. Current version: 2.5.0, with frequent minor releases. Requires Python >=3.10.

devops

pip install nonebot2

github ↗homepage ↗

INSTALL

IMPORT

SIG · NONEBOT2

nonebot2

devopspythonv2.5.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Bot

✓ from nonebot import Bot

Bot is now imported from nonebot top-level.

on_command

✓ from nonebot.plugin import on_command

✗ from nonebot import on_command

on_command moved to nonebot.plugin in v2.0.

Matcher

✓ from nonebot.matcher import Matcher

✗ from nonebot import Matcher

Matcher is in its own module.

Initialize NoneBot2, register the OneBot v11 adapter, load built-in plugins, and run.

import nonebot from nonebot.adapters.onebot.v11 import Adapter as OneBotAdapter nonebot.init() driver = nonebot.get_driver() driver.register_adapter(OneBotAdapter) nonebot.load_builtin_plugins() nonebot.run()

Debug

Known issues

breakingIn v2.0, the framework was rewritten. Old v1.x plugins are incompatible. Rewrite plugins using new API.

fix

Migrate plugins to use new imports (from nonebot.plugin, nonebot.matcher, etc.) and event handlers.

affects: >=2.0.0

gotchaDo not call nonebot.run() inside an async event loop. It will raise RuntimeError.

fix

Run as a script directly, not inside an async context.

affects: >=2.0.0

gotchaPlugin loading is case-sensitive on most filesystems. Use lowercase file names and match them in load_plugin.

fix

Ensure plugin file names are lowercase and consistent.

affects: >=2.0.0

deprecatedThe 'nonebot.log' module is deprecated. Use 'nonebot.utils.logger' instead.

fix

Replace 'from nonebot.log import logger' with 'from nonebot.utils import logger'.

affects: >=2.4.0

Errors

Common errors & fixes

RuntimeError: Cannot run the event loop while another loop is running

Calling nonebot.run() inside an async function or Jupyter notebook.

fix

Move the run call to the top-level script, outside any async context.

ImportError: cannot import name 'on_command' from 'nonebot'

Importing on_command directly from nonebot instead of nonebot.plugin.

fix

Use 'from nonebot.plugin import on_command'.

ModuleNotFoundError: No module named 'nonebot.adapters.onebot'

Missing adapter package installation.

fix

Install the adapter: pip install nonebot-adapter-onebot.

Upgrade

Version history

2.5.0latest on PyPI · released Apr 1, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/nonebot/nonebot2 ↗

homepagehttps://github.com/nonebot/nonebot2 ↗