Downloader & Repo Manager
Relevant source files
The following files were used as context for generating this wiki page:
The Downloader and Repo Manager system enables the installation, management, and updating of third-party plugins (cogs) from external Git repositories. It provides a modular extension framework for Red, allowing bot owners to add functionality beyond the built-in core modules.
Sources: README.md, redbot/cogs/downloader/downloader.py
System Architecture
The system consists of three primary layers: the User Interface (Discord commands), the Downloader Cog (installation logic), and the Repo Manager (git and filesystem operations).
Architecture Overview
The Downloader cog handles the high-level logic for finding and installing cogs, while the Repo Manager interacts directly with the local filesystem and external version control systems to retrieve source code.
Sources: redbot/cogs/downloader/downloader.py, redbot/cogs/downloader/repo_manager.py
Cog Metadata and Schemas
Every cog and repository managed by the Downloader must adhere to specific metadata formats. These are validated against JSON schemas to ensure compatibility with the bot's version and environment requirements.
Metadata Field Descriptions
| Field | Type | Description |
|---|---|---|
author | Array | List of cog author names. |
min_bot_version | String | Minimum Red version required (e.g., "3.5.0"). |
min_python_version | Array | Minimum Python version as [MAJOR, MINOR, PATCH]. |
requirements | Array | List of library dependencies to be installed via pip. |
hidden | Boolean | Whether the cog is hidden in repository lists. |
end_user_data_statement | String | Explanation of what data the cog stores. |
Sources: schema/red_cog.schema.json:7-124, schema/red_cog_repo.schema.json:7-30
Installation and Update Logic
The installation process involves verifying dependencies, cloning the repository, and moving the specific cog files into the bot's installation directory. The bot also supports automated updates for all installed cogs.
Installation Sequence
When an update occurs, the bot compares the local hash of the cog with the remote Git branch. If they differ, the Repo Manager pulls the new code and the Downloader triggers a reload of the module.
Sources: redbot/cogs/downloader/downloader.py, redbot/_update/internal.py:64-150
Dependency Management
The Downloader handles Python library dependencies through pip. If a cog defines a requirements list in its metadata, the bot attempts to install these libraries into the instance's library folder.
Requirement Reinstallation
During major updates (such as Python version changes), the bot automatically clears the lib folder and triggers a full reinstallation of all requirements for every installed cog to ensure environment consistency.
Sources: redbot/_update/internal.py:88-112, redbot/core/core_commands.py:476-492
Data Deletion and Privacy
The Downloader respects Red's data privacy framework. It implements a data deletion handler to manage information regarding installed repositories when a bot owner or Discord requests data removal.
Sources: redbot/core/core_commands.py:672-748, redbot/cogs/downloader/downloader.py
The Downloader and Repo Manager system provides the foundation for Red's modularity, ensuring that third-party extensions are safely managed, version-checked, and integrated into the bot's lifecycle.