Bot Updater & Runner
Relevant source files
The following files were used as context for generating this wiki page:
The Bot Updater & Runner system manages the lifecycle of the Red Discord Bot installation, including version checks, virtual environment migration, and automated updates. It ensures the bot remains current by fetching metadata from PyPI and guiding the user through major, minor, and hotfix updates.
This system handles the transition between bot versions by creating fresh virtual environments and migrating existing instances. It also manages third-party cog compatibility during the update process to prevent breaking changes from disabling bot functionality.
Update Lifecycle
The update process follows a structured sequence to ensure data safety and system stability. It begins with version discovery and ends with a cleanup of the old environment.
Workflow Logic
- Metadata Preparation: The system fetches available versions and determines the target version based on user options.
- Compatibility Check: It validates whether installed third-party cogs are compatible with the target Red and Python versions.
- Backup Execution: The system creates a compressed backup of the current virtual environment and bot instances.
- Virtual Environment Migration: It moves the old environment to a backup directory and prepares a fresh installation in the primary directory.
- Finalization: A separate internal process finishes the update by installing dependencies and rendering changelogs.
Sources: redbot/_update/updater.py:166-210, redbot/_update/internal.py:276-324
Update Execution Flow
The following diagram illustrates the transition from the old version to the new version using a fresh virtual environment.
The diagram shows how the system ensures a rollback path by moving the old environment before installing the new one. Sources: redbot/_update/updater.py:465-492, redbot/_update/internal.py:276-310
Component Architecture
The updater system is divided into high-level management classes and low-level internal command-line interfaces.
Updater & UpdaterMetadata
The Updater class coordinates the high-level logic, while UpdaterMetadata stores the state of the update across different process executions. Since the update often involves replacing the Python interpreter or the Red package itself, the system uses JSON-serialized metadata to maintain continuity.
| Component | Responsibility |
|---|---|
UpdaterOptions | Stores user-defined flags like --no-backup or --red-version. |
UpdaterMetadata | Captures system info, changelogs, and compatibility results. |
BackupResults | Tracks which instances were successfully backed up. |
Updater | Orchestrates the primary update loop and user interactions. |
Sources: redbot/_update/updater.py:33-149
Internal CLI
The redbot._update.internal module provides hidden commands used by the system to perform tasks that require a specific environment or limited scope.
update-cogs: Updates third-party cogs for a specific instance.finish-update: The final step that runs within the new virtual environment to finalize the installation.reinstall: Handles the actualpipinstallation of the new Red version.
Sources: redbot/_update/internal.py:31-40, redbot/_update/internal.py:231-235
Version and Environment Validation
The system enforces strict requirements for Python and bot versions to ensure operational integrity.
Python Version Requirements
Red requires a minimum Python version of 3.8.1. If the current interpreter does not meet this requirement, the bot terminates with an error. During an update, if the target Red version requires a newer Python version than the one currently in use, the updater searches the system for compatible interpreters.
Sources: redbot/init.py:23-28, redbot/_update/updater.py:328-360
Outdated Version Alerts
The bot monitors its own version against the latest release on PyPI. If an update is available, it notifies the bot owner through Discord messages and prints a warning to the console.
def get_outdated_red_messages(pypi_version: str) -> Tuple[str, str]:
outdated_red_message = _(
"Your Red instance is out of date! {} is the current version, however you are using {}!"
).format(pypi_version, red_version)
# ... command instructions follow
Sources: redbot/core/_events.py:53-83
Instance and Cog Management
The updater manages multiple bot instances and their associated third-party cogs.
Compatibility Checks
Before proceeding with an update, the system checks the compatibility of cogs across all specified instances. It categorizes results into checked, failed, and skipped instances. This prevents users from updating to a version that would render their primary cogs non-functional.
Sources: redbot/_update/updater.py:392-446
Automated Backups
The system performs two types of backups:
- VENV Backup: A
tar.gzarchive of the entire virtual environment directory. - Instance Backup: Individual backups of each bot instance's data using the
redbot.setup backupcommand.
Sources: redbot/_update/updater.py:448-463
User Interface and Feedback
The updater provides feedback through both the console (using the rich library) and Discord.
Changelog Rendering
The system fetches changelogs from the official documentation site. It parses these logs to identify "Read before updating" sections and lists of contributors. During interactive updates, it can launch a Terminal User Interface (TUI) for the user to browse changes.
Sources: redbot/_update/changelog.py:84-110, redbot/_update/updater.py:291-326
Core Settings
Users can view and manage related system information through core bot commands.
| Command | Description |
|---|---|
[p]info | Displays current Red, Python, and discord.py versions. |
[p]debuginfo | Provides detailed system metadata, OS variables, and Red variables. |
[p]datapath | Prints the path where bot data is stored. |
Sources: redbot/core/core_commands.py:321-468, redbot/core/core_commands.py:1682-1688
Conclusion
The Bot Updater & Runner system is a robust utility that minimizes the risks associated with software updates. By automating virtual environment recreation, performing multi-layered backups, and validating cog compatibility, it ensures that instance administrators can maintain their bots with minimal technical friction. Its ability to handle cross-version Python migrations makes it essential for long-term project maintenance.