Red-DiscordBot

3.5.24 · active · verified Mon Apr 13

Red-DiscordBot is a highly customisable, self-hosted Discord bot framework, offering a wide array of features through its modular 'cogs' (plugins). It supports everything from moderation and utility to music and custom commands. The project maintains an active development cycle with frequent patch releases, often aligning with updates to its core dependencies like discord.py.

Warnings

breaking Red-DiscordBot V3.5+ depends on `discord.py` V2.x. Cogs (plugins) written for older Red versions (V3.0-V3.4, which used `discord.py` V1.x) will likely require significant updates due to breaking changes in `discord.py`'s API (e.g., `Intents` are now mandatory).
Fix: Review the `discord.py` V2 migration guide and Red's cog migration documentation. Update affected cogs to conform to the new API.
breaking Migrating from Red V2 to Red V3 involves fundamental architectural changes. Cogs are now Python packages, data storage shifted from `dataIO` to the `Config` system, and core utilities are imported with a `redbot.core` prefix. Older cogs will not function without a complete rewrite or significant refactoring.
Fix: Follow the official 'Migrating cogs from Red V2' guide in the Red-DiscordBot documentation.
breaking Red V3.2 dropped support for the MongoDB data backend. If you were using MongoDB with an older Red version, you must migrate your data to a supported backend (e.g., JSON, PostgreSQL) before updating to Red V3.2 or later.
Fix: Consult the Red-DiscordBot documentation for data migration paths if currently using MongoDB.
gotcha Achieving full audio functionality, especially for streaming from sources like YouTube or Spotify, often requires additional system-level dependencies. This includes a Java Runtime Environment (JRE 11+) for the Lavalink audio server and FFmpeg for media processing. Troubleshooting audio issues can be complex due to these external requirements.
Fix: Ensure JRE 11+ and FFmpeg are installed system-wide. For advanced setups, refer to the Lavalink setup guide in the Red-DiscordBot documentation.
gotcha Red-DiscordBot highly recommends (and often implicitly requires) installation within a Python virtual environment. Failure to use a virtual environment can lead to dependency conflicts with other Python projects or system-wide package pollution, making future updates or dependency management difficult.
Fix: Always create and activate a Python virtual environment (`python -m venv redenv && source redenv/bin/activate` or `redenv\Scripts\activate.bat`) before installing or updating Red-DiscordBot.
gotcha Red-DiscordBot is primarily controlled through its command-line interface for initial setup (`redbot-setup`) and starting the bot (`redbot <instance_name>`). Once running, all bot commands and cog interactions are performed within Discord chat, not the terminal. New users often mistakenly try to type bot commands into the terminal console.
Fix: Understand the distinction between the host terminal for bot management and Discord chat for bot commands. Ensure the bot has necessary Discord permissions (Read Messages, Send Messages) in channels you intend to use it.

Install

pip install -U Red-DiscordBot Base Installation
pip install -U Red-DiscordBot[postgres] With PostgreSQL Support

Imports

Red
```
from redbot.core.bot import Red
```
Red bot instance is explicitly in `redbot.core.bot`.
commands
```
from redbot.core import commands
```
Red wraps and extends `discord.ext.commands`.
Config
```
from redbot.core import Config
```
`Config` replaced `dataIO` for data storage in Red V3.

Quickstart

Red-DiscordBot is primarily managed via a command-line interface and in-Discord commands. To get started, you first install Red into a virtual environment. Then, you run `redbot-setup <instance_name>` in your terminal, which guides you through creating a bot, setting a prefix, and obtaining the bot token. You then start the bot using `redbot <instance_name>`. The bot provides an invite URL, and once invited to a server, you can interact with it using the configured prefix (e.g., `[p]help`). This example shows a simple 'cog' (plugin) that defines two commands. Save this as `mysimplecog.py` in your cogs directory, then load it in Discord using `[p]load mysimplecog`.

import discord
from redbot.core import commands

class MySimpleCog(commands.Cog):
    """My super awesome cog!"""

    def __init__(self, bot):
        self.bot = bot

    @commands.command()
    async def hello(self, ctx):
        """Says hello!"""
        await ctx.send("Hello, world!")

    @commands.command()
    async def myid(self, ctx):
        """Shows your Discord ID."""
        await ctx.send(f"Your ID is: {ctx.author.id}")

async def setup(bot):
    await bot.add_cog(MySimpleCog(bot))

view raw JSON →