Bazel registries

Bzlmod discovers dependencies by requesting their information from Bazel registries: databases of Bazel modules. Currently, Bzlmod only supports index registries — local directories or static HTTP servers following a specific format.

Index registry

An index registry is a local directory or a static HTTP server containing information about a list of modules — including their homepage, maintainers, the MODULE.bazel file of each version, and how to fetch the source of each version. Notably, it does not need to serve the source archives itself.

An index registry must follow the format below:

• /bazel_registry.json: A JSON file containing metadata for the registry like:
  • mirrors: specifying the list of mirrors to use for source archives. The mirrored URL is a concatenation of the mirror itself, and the source URL of the module specified by its source.json file sans the protocol. For example, if a module's source URL is https://foo.com/bar/baz, and mirrors contains ["https://mirror1.com/", "https://example.com/mirror2/"], then the URLs Bazel will try in order are https://mirror1.com/foo.com/bar/baz, https://example.com/mirror2/foo.com/bar/baz, and finally the original source URL itself https://foo.com/bar/baz.
  • module_base_path: specifying the base path for modules with local_repository type in the source.json file
• /modules: A directory containing a subdirectory for each module in this registry
• /modules/$MODULE: A directory containing a subdirectory for each version of this module, as well as:
  • metadata.json: A JSON file containing information about the module, with the following fields:
    • homepage: The URL of the project's homepage
    • maintainers: A list of JSON objects, each of which corresponds to the information of a maintainer of the module in the registry. Note that this is not necessarily the same as the authors of the project
    • versions: A list of all the versions of this module to be found in this registry
    • yanked_versions: A map of yanked versions of this module. The keys should be versions to yank and the values should be descriptions of why the version is yanked, ideally containing a link to more information
• /modules/$MODULE/$VERSION: A directory containing the following files:
  • MODULE.bazel: The MODULE.bazel file of this module version
  • source.json: A JSON file containing information on how to fetch the source of this module version
    • The default type is "archive", representing an http_archive repo, with the following fields:
      • url: The URL of the source archive
      • integrity: The Subresource Integrity checksum of the archive
      • strip_prefix: A directory prefix to strip when extracting the source archive
      • patches: A map containing patch files to apply to the extracted archive. The patch files are located under the /modules/$MODULE/$VERSION/patches directory. The keys are the patch file names, and the values are the integrity checksum of the patch files
      • patch_strip: Same as the --strip argument of Unix patch.
      • archive_type: The archive type of the downloaded file (Same as type on http_archive). By default, the archive type is determined from the file extension of the URL. If the file has no extension, you can explicitly specify one of the following: "zip", "jar", "war", "aar", "tar", "tar.gz", "tgz", "tar.xz", "txz", "tar.zst", "tzst", tar.bz2, "ar", or "deb".
    • The type can be changed to use a git repository, with these fields:
      • type: git_repository
      • The following fields as described at https://bazel.build/rules/lib/repo/git:
        • remote
        • commit
        • shallow_since
        • tag
        • init_submodules
        • verbose
        • strip_prefix
    • The type can be changed to use a local path, representing a local_repository repo, with these fields:
      • type: local_path
      • path: The local path to the repo, calculated as following:
        • If path is an absolute path, it stays as it is
        • If path is a relative path and module_base_path is an absolute path, it resolves to <module_base_path>/<path>
        • If path and module_base_path are both relative paths, it resolves to <registry_path>/<module_base_path>/<path>. Registry must be hosted locally and used by --registry=file://<registry_path>. Otherwise, Bazel will throw an error
  • patches/: An optional directory containing patch files, only used when source.json has "archive" type

Bazel Central Registry

The Bazel Central Registry (BCR) at https://bcr.bazel.build/ is an index registry with contents backed by the GitHub repo bazelbuild/bazel-central-registry. You can browse its contents using the web frontend at https://registry.bazel.build/.

The Bazel community maintains the BCR, and contributors are welcome to submit pull requests. See the BCR contribution guidelines.

In addition to following the format of a normal index registry, the BCR requires a presubmit.yml file for each module version (/modules/$MODULE/$VERSION/presubmit.yml). This file specifies a few essential build and test targets that you can use to check the validity of this module version. The BCR's CI pipelines also uses this to ensure interoperability between modules.

Selecting registries

The repeatable Bazel flag --registry can be used to specify the list of registries to request modules from, so you can set up your project to fetch dependencies from a third-party or internal registry. Earlier registries take precedence. For convenience, you can put a list of --registry flags in the .bazelrc file of your project.

If your registry is hosted on GitHub (for example, as a fork of bazelbuild/bazel-central-registry) then your --registry value needs a raw GitHub address under raw.githubusercontent.com. For example, on the main branch of the my-org fork, you would set --registry=https://raw.githubusercontent.com/my-org/bazel-central-registry/main/.

Using the --registry flag stops the Bazel Central Registry from being used by default, but you can add it back by adding --registry=https://bcr.bazel.build.