Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
Red is a modular Discord bot built with Python that allows users to host their own instances. It provides a customizable framework where features (cogs) can be loaded or unloaded to suit specific needs, such as moderation, music, or trivia. Sources: README.md:1-5, README.md:37-39
The project requires a self-hosted environment and supports major platforms including Windows, MacOS, and Linux. For developers, Red follows a specific workflow using virtual environments, standardized formatting with Black, and testing via Tox to ensure cross-compatibility and code quality. Sources: README.md:52-57, CONTRIBUTING.md:46-51
System Requirements
Red mandates specific software versions to ensure stability and compatibility with the Discord API.
| Requirement | Supported Versions | Notes |
|---|---|---|
| Python | 3.8.1 or greater | Enforced via runtime check. |
| Git | Latest stable | Required for cloning and version control. |
| pip | Latest stable | Used for dependency management. |
| GNU Make | Latest (Posix only) | Used for development environment scripts. |
Sources: CONTRIBUTING.md:73-77, redbot/init.py:24-30, pyproject.toml:22-26
Runtime Version Validation
The bot performs a version check upon initialization. If the Python version is lower than 3.8.1, the process exits with code 78. Sources: redbot/init.py:24-32
Installation for Users
Installation focuses on setting up the environment and launching the bot via provided CLI scripts. Red uses entry points defined in pyproject.toml to expose management commands. Sources: pyproject.toml:44-46
- Prepare the Host: Ensure Python 3.8.1+ and pip are installed. Sources: CONTRIBUTING.md:73-76
- Install Red-DiscordBot: Install the package via pip.
- Setup the Instance: Run
redbot-setupto configure the data path and instance name. Sources: pyproject.toml:46 - Launch the Bot: Execute
redbot <instance_name>to start the bot. Sources: pyproject.toml:45
The Startup Sequence
When the bot starts, it executes an internal on_ready sequence to verify the environment and display system information.
Sources: redbot/core/_events.py:101-160
Development Environment Setup
Developers contributing to Red must use a standardized virtual environment to maintain dependency consistency. Sources: CONTRIBUTING.md:71-72
Environment Initialization
Red provides a Makefile (and make.bat for Windows) to automate environment creation. Sources: CONTRIBUTING.md:128-132
- make newenv: Creates a
.venvsubdirectory, installs dependencies, and installs Red in editable mode. Sources: CONTRIBUTING.md:83-88 - make syncenv: Synchronizes the environment with the latest dependencies from
setup.cfgortools/dev-requirements.txt. Sources: CONTRIBUTING.md:133-134
Activation Commands
| Platform | Command |
|---|---|
| Posix | source .venv/bin/activate |
| Windows | .venv\Scripts\activate |
Sources: CONTRIBUTING.md:92-97
Core Configuration and Interaction
Once Red is running, owners interact with the bot through Discord commands or CLI flags to set global parameters.
Prefix Management
Owners set global or server-specific prefixes to define how the bot responds to commands. Prefixes cannot start with a forward slash (/) to avoid conflict with Discord slash commands. Sources: redbot/core/core_commands.py:1262-1265, redbot/core/core_commands.py:1334-1337
Application Command Management
Red supports Discord Application Commands (Slash Commands). Owners must manually sync these commands to Discord after enabling them. Sources: redbot/core/core_commands.py:730-735, redbot/core/core_commands.py:917-920
- [p]slash enable: Marks a command as enabled in the bot's internal tree. Sources: redbot/core/core_commands.py:741-750
- [p]slash sync: Communicates the current state of enabled commands to Discord's API. Sources: redbot/core/core_commands.py:917-925
Contribution Workflow
To contribute changes to the repository, developers must follow the project's ground rules and style guides. Sources: CONTRIBUTING.md:58-69
Development Guidelines
- Style: Code must be formatted with Black. The line length is set to 99 characters. Sources: CONTRIBUTING.md:118-124, pyproject.toml:50-51
- Testing: Use
toxto run unit tests (pytest), documentation builds, and style checks. Sources: CONTRIBUTING.md:102-111 - Cross-compatibility: Code must work on Windows, MacOS, and Linux using Python 3.8.1+. Sources: CONTRIBUTING.md:46-49
Submitting Changes
- Fork and clone the repository.
- Create a branch on your fork.
- Implement changes and add new tests.
- Run
toxto ensure all tests pass. - Open a Pull Request (PR) on GitHub.
Sources: CONTRIBUTING.md:139-148
Summary
Getting started with Red requires establishing a Python 3.8.1+ environment and selecting either a user-centric installation via pip or a developer-centric setup using the provided virtual environment tools. The bot's modular nature allows owners to customize functionality through cogs immediately after the startup sequence completes. Sources: README.md:1-5, CONTRIBUTING.md:83-88, redbot/core/_events.py:155-160