Downloader Framework


The optional info.json file may exist inside every package folder in the repo, as well as in the root of the repo. The following sections describe the valid keys within an info file (and maybe how the Downloader cog uses them).

Keys common to both repo and cog info.json (case sensitive)

  • author (list of strings) - list of names of authors of the cog or repo.

  • description (string) - A long description of the cog or repo. For cogs, this is displayed when a user executes !cog info.

  • install_msg (string) - The message that gets displayed when a cog is installed or a repo is added


    You can use the [p] key in your string to use the prefix used for installing.

  • short (string) - A short description of the cog or repo. For cogs, this info is displayed when a user executes !cog list

Keys specific to the cog info.json (case sensitive)

  • min_bot_version (string) - Min version number of Red in the format MAJOR.MINOR.MICRO
  • max_bot_version (string) - Max version number of Red in the format MAJOR.MINOR.MICRO, if min_bot_version is newer than max_bot_version, max_bot_version will be ignored
  • hidden (bool) - Determines if a cog is visible in the cog list for a repo.
  • disabled (bool) - Determines if a cog is available for install.
  • required_cogs (map of cogname to repo URL) - A map of required cogs that this cog depends on. Downloader will not deal with this functionality but it may be useful for other cogs.
  • requirements (list of strings) - list of required libraries that are passed to pip on cog install. SHARED_LIBRARIES do NOT go in this list.
  • tags (list of strings) - A list of strings that are related to the functionality of the cog. Used to aid in searching.
  • type (string) - Optional, defaults to COG. Must be either COG or SHARED_LIBRARY. If SHARED_LIBRARY then hidden will be True.

API Reference


class redbot.cogs.downloader.installable.Installable(location: pathlib.Path)[source]

Base class for anything the Downloader cog can install.

  • Modules
  • Repo Libraries
  • Other stuff?

The attributes of this class will mostly come from the installation’s info.json.


Name of the repository which this package belongs to.


Name(s) of the author(s).

Type:tuple of str, optional

The minimum bot version required for this installation. Right now this is always 3.0.0.

Type:tuple of int

The minimum python version required for this cog. This field will not apply to repo info.json’s.

Type:tuple of int

Whether or not this cog will be hidden from the user when they use Downloader’s commands.


In the form {cog_name : repo_url}, these are cogs which are required for this installation.


Required libraries for this installation.

Type:tuple of str

List of tags to assist in searching.

Type:tuple of str

The type of this installation, as specified by InstallationType.

coroutine copy_to(target_dir: pathlib.Path) → bool[source]

Copies this cog/shared_lib to the given directory. This will overwrite any files in the target directory.

Parameters:target_dir (pathlib.Path) – The installation directory to install to.
Returns:Status of installation
Return type:bool

The name of this package.



class redbot.cogs.downloader.repo_manager.Repo(name: str, url: str, branch: str, folder_path: pathlib.Path, available_modules: Tuple[redbot.cogs.downloader.installable.Installable] = (), loop: = None)[source]

All available cogs in this Repo.

This excludes hidden or shared packages.

Type:tuple of installable

All available shared libraries in this Repo.

Type:tuple of installable
coroutine clone() → Tuple[str][source]

Clone a new repo.

Returns:All available module names from this repo.
Return type:tuple of str
coroutine current_branch() → str[source]

Determine the current branch using git commands.

Returns:The current branch name.
Return type:str
coroutine current_commit(branch: str = None) → str[source]

Determine the current commit hash of the repo.

Parameters:branch (str, optional) – Override for repo’s branch attribute.
Returns:The requested commit hash.
Return type:str
coroutine current_url(folder: pathlib.Path = None) → str[source]

Discovers the FETCH URL for a Git repo.

Parameters:folder (pathlib.Path) – The folder to search for a URL.
Returns:The FETCH URL.
Return type:str
Raises:NoRemoteURL – When the folder does not contain a git repo with a FETCH URL.
coroutine hard_reset(branch: str = None) → None[source]

Perform a hard reset on the current repo.

Parameters:branch (str, optional) – Override for repo branch attribute.
coroutine install_cog(cog: redbot.cogs.downloader.installable.Installable, target_dir: pathlib.Path) → bool[source]

Install a cog to the target directory.

  • cog (Installable) – The package to install.
  • target_dir (pathlib.Path) – The target directory for the cog installation.

The success of the installation.

Return type:


coroutine install_libraries(target_dir: pathlib.Path, req_target_dir: pathlib.Path, libraries: Tuple[redbot.cogs.downloader.installable.Installable] = ()) → bool[source]

Install shared libraries to the target directory.

If libraries is not specified, all shared libraries in the repo will be installed.

  • target_dir (pathlib.Path) – Directory to install shared libraries to.
  • req_target_dir (pathlib.Path) – Directory to install shared library requirements to.
  • libraries (tuple of Installable) – A subset of available libraries.

The success of the installation.

Return type:


coroutine install_raw_requirements(requirements: Tuple[str], target_dir: pathlib.Path) → bool[source]

Install a list of requirements using pip.

  • requirements (tuple of str) – List of requirement names to install via pip.
  • target_dir (pathlib.Path) – Path to directory where requirements are to be installed.

Success of the installation

Return type:


coroutine install_requirements(cog: redbot.cogs.downloader.installable.Installable, target_dir: pathlib.Path) → bool[source]

Install a cog’s requirements.

Requirements will be installed via pip directly into target_dir.

  • cog (Installable) – Cog for which to install requirements.
  • target_dir (pathlib.Path) – Path to directory where requirements are to be installed.

Success of the installation.

Return type:


coroutine update() -> (<class 'str'>, <class 'str'>)[source]

Update the current branch of this repo.

Returns::py:code`(old commit hash, new commit hash)`
Return type:tuple of str

Repo Manager

class redbot.cogs.downloader.repo_manager.RepoManager[source]
coroutine add_repo(url: str, name: str, branch: Optional[str] = None) → redbot.cogs.downloader.repo_manager.Repo[source]

Add and clone a git repository.

  • url (str) – URL to the git repository.
  • name (str) – Internal name of the repository.
  • branch (str) – Name of the default branch to checkout into.

New Repo object representing the cloned repository.

Return type:


coroutine delete_repo(name: str)[source]

Delete a repository and its folders.

Parameters:name (str) – The name of the repository to delete.
Raises:MissingGitRepo – If the repo does not exist.
get_all_repo_names() → Tuple[str][source]

Get all repo names.

Return type:tuple of str
get_repo(name: str) → Optional[redbot.cogs.downloader.repo_manager.Repo][source]

Get a Repo object for a repository.

Parameters:name (str) – The name of the repository to retrieve.
Returns:Repo object for the repository, if it exists.
Return type:Repo or None
coroutine update_all_repos() → MutableMapping[redbot.cogs.downloader.repo_manager.Repo, Tuple[str, str]][source]

Call Repo.update on all repositories.

Returns:A mapping of Repo objects that received new commits to a tuple of str containing old and new commit hashes.
Return type:dict


exception redbot.cogs.downloader.errors.DownloaderException[source]

Base class for Downloader exceptions.

exception redbot.cogs.downloader.errors.GitException[source]

Generic class for git exceptions.

exception redbot.cogs.downloader.errors.InvalidRepoName[source]

Throw when a repo name is invalid. Check the message for a more detailed reason.

exception redbot.cogs.downloader.errors.ExistingGitRepo[source]

Thrown when trying to clone into a folder where a git repo already exists.

exception redbot.cogs.downloader.errors.MissingGitRepo[source]

Thrown when a git repo is expected to exist but does not.

exception redbot.cogs.downloader.errors.CloningError[source]

Thrown when git clone returns a non zero exit code.

exception redbot.cogs.downloader.errors.CurrentHashError[source]

Thrown when git returns a non zero exit code attempting to determine the current commit hash.

exception redbot.cogs.downloader.errors.HardResetError[source]

Thrown when there is an issue trying to execute a hard reset (usually prior to a repo update).

exception redbot.cogs.downloader.errors.UpdateError[source]

Thrown when git pull returns a non zero error code.

exception redbot.cogs.downloader.errors.GitDiffError[source]

Thrown when a git diff fails.

exception redbot.cogs.downloader.errors.NoRemoteURL[source]

Thrown when no remote URL exists for a repo.

exception redbot.cogs.downloader.errors.PipError[source]

Thrown when pip returns a non-zero return code.