{"id":5454,"library":"red-discordbot","title":"Red-DiscordBot","description":"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.","status":"active","version":"3.5.24","language":"en","source_language":"en","source_url":"https://github.com/Cog-Creators/Red-DiscordBot","tags":["discord","bot","framework","extensible","python-bot"],"install":[{"cmd":"pip install -U Red-DiscordBot","lang":"bash","label":"Base Installation"},{"cmd":"pip install -U Red-DiscordBot[postgres]","lang":"bash","label":"With PostgreSQL Support"}],"dependencies":[{"reason":"Core dependency for Discord API interaction, bundled implicitly with Red.","package":"discord.py","optional":false},{"reason":"Required for Audio cog's Lavalink support.","package":"Java Runtime Environment 11+","optional":true},{"reason":"System-level dependency for audio processing, used by the Audio cog.","package":"FFmpeg","optional":true},{"reason":"Optional backend for data storage, specified during installation with `[postgres]` extra.","package":"PostgreSQL","optional":true},{"reason":"Pre-requirement for certain installation methods and cog management.","package":"git","optional":false}],"imports":[{"note":"Red bot instance is explicitly in `redbot.core.bot`.","wrong":"from redbot.core import Red","symbol":"Red","correct":"from redbot.core.bot import Red"},{"note":"Red wraps and extends `discord.ext.commands`.","wrong":"from discord.ext import commands","symbol":"commands","correct":"from redbot.core import commands"},{"note":"`Config` replaced `dataIO` for data storage in Red V3.","wrong":"from redbot.core.dataio import dataIO","symbol":"Config","correct":"from redbot.core import Config"}],"quickstart":{"code":"import discord\nfrom redbot.core import commands\n\nclass MySimpleCog(commands.Cog):\n    \"\"\"My super awesome cog!\"\"\"\n\n    def __init__(self, bot):\n        self.bot = bot\n\n    @commands.command()\n    async def hello(self, ctx):\n        \"\"\"Says hello!\"\"\"\n        await ctx.send(\"Hello, world!\")\n\n    @commands.command()\n    async def myid(self, ctx):\n        \"\"\"Shows your Discord ID.\"\"\"\n        await ctx.send(f\"Your ID is: {ctx.author.id}\")\n\nasync def setup(bot):\n    await bot.add_cog(MySimpleCog(bot))","lang":"python","description":"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`."},"warnings":[{"fix":"Review the `discord.py` V2 migration guide and Red's cog migration documentation. Update affected cogs to conform to the new API.","message":"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).","severity":"breaking","affected_versions":"3.5.0+"},{"fix":"Follow the official 'Migrating cogs from Red V2' guide in the Red-DiscordBot documentation.","message":"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.","severity":"breaking","affected_versions":"3.0.0+"},{"fix":"Consult the Red-DiscordBot documentation for data migration paths if currently using MongoDB.","message":"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.","severity":"breaking","affected_versions":"3.2.0+"},{"fix":"Ensure JRE 11+ and FFmpeg are installed system-wide. For advanced setups, refer to the Lavalink setup guide in the Red-DiscordBot documentation.","message":"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.","severity":"gotcha","affected_versions":"All V3.x"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All V3.x"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All V3.x"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}