Bazel registries

Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Bazel discovers dependencies by requesting their information from Bazel registries: databases of Bazel modules. Bazel only supports one type of registries — 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 have the following format:

  • /bazel_registry.json: An optional JSON file containing metadata for the registry.
  • /modules: A directory containing a subdirectory for each module in this registry
  • /modules/$MODULE: A directory containing a subdirectory for each version of the module named $MODULE, as well as the metadata.json file containing metadata for this module.
  • /modules/$MODULE/$VERSION: A directory containing the following files:
    • MODULE.bazel: The MODULE.bazel file of this module version. Note that this is the MODULE.bazel file read during Bazel's external dependency resolution, not the one from the source archive (unless there's a non-registry override). Also note that it's best to use this file to set the version of a release and avoid doing so in the source archive MODULE.bazel file. To learn more about module versioning, see the FAQ.
    • source.json: A JSON file containing information on how to fetch the source of this module version
    • patches/: An optional directory containing patch files, only used when source.json has "archive" type
    • overlay/: An optional directory containing overlay files, only used when source.json has "archive" type

bazel_registry.json

bazel_registry.json is an optional file that specifies metadata applying to the entire registry. It can contain the following fields:

  • mirrors: an array of strings, 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: a string, specifying the base path for modules with local_path type in the source.json file

metadata.json

metadata.json is an optional JSON file containing information about the module, with the following fields:

  • versions: An array of strings, each denoting a version of the module available in this registry. This array should match the children of the module directory.
  • yanked_versions: A JSON object specifying the 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.

Note that the BCR requires more information in the metadata.json file.

source.json

source.json is a required JSON file containing information about how to fetch a specific version of a module. The schema of this file depends on its type field, which defaults to archive.

  • If type is archive (the default), this module version is backed by an http_archive repo rule; it's fetched by downloading an archive from a given URL and extracting its contents. It supports the following fields:
    • url: A string, the URL of the source archive
    • mirror_urls: A list of string, the mirror URLs of the source archive. The URLs are tried in order after url as backups.
    • integrity: A string, the Subresource Integrity checksum of the archive
    • strip_prefix: A string, the directory prefix to strip when extracting the source archive
    • overlay: A JSON object containing overlay files to layer on top of the extracted archive. The patch files are located under the /modules/$MODULE/$VERSION/overlay directory. The keys are the overlay file names, and the values are the integrity checksum of the overlay files. The overlays are applied before the patch files.
    • patches: A JSON object 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. The patches are applied after the overlay files and in the order they appear in patches.
    • patch_strip: A number; the same as the --strip argument of Unix patch.
    • archive_type: A string, the archive type of the downloaded file (Same as type on http_archive).
  • If type is git_repository, this module version is backed by a git_repository repo rule; it's fetched by cloning a Git repository.
    • The following fields are supported, and are directly forwarded to the underlying git_repository repo rule: remote, commit, shallow_since, tag, init_submodules, verbose, and strip_prefix.
  • If type is local_path, this module version is backed by a local_repository repo rule; it's symlinked to a directory on local disk. It supports the following field:
    • 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

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.