> ## Documentation Index
> Fetch the complete documentation index at: https://site.aspect.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Install

> Learn how to install Gazelle for Bazel using a pre-built binary, the Aspect CLI configure command, or by building a custom gazelle_binary from source.

## Pre-built binary

We recommend that developers execute a pre-compiled binary.

1. You could create a custom workflow for your repository to build the binary when needed, for the right architectures, and then publish it somewhere that your developers use. Consider creating a `tools/gazelle` redirect in the repo to make it easy to locate - see [run tools installed by bazel](/blog/run-tools-installed-by-bazel)
2. <Icon icon="https://mintcdn.com/aspectbuild/gtqBKXWWd-jWHweY/logo/icon.png?fit=max&auto=format&n=gtqBKXWWd-jWHweY&q=85&s=0639e7d5498c5c9cd0924dbe51dc7653" size={20} width="144" height="128" data-path="logo/icon.png" /> Much easier: use the `aspect gazelle` task in the free Aspect CLI, which runs the pre-built [aspect-gazelle](https://github.com/aspect-build/aspect-gazelle) binaries, no compilation required. See [the aspect gazelle task](/docs/cli/tasks/gazelle) for setup and the built-in language extensions.
   This includes the ability to write extensions in Starlark, which we’ll explore extensively.

### Using `aspect_gazelle_prebuilt`

The prebuilt binary is distributed as a Bazel module, so wiring it up is two snippets. The [`aspect_gazelle_prebuilt` README](https://github.com/aspect-build/aspect-gazelle/blob/main/prebuilt/README.md) documents how to wire up the `aspect_gazelle()` macro and all its options. Add the dependency to `MODULE.bazel`:

```python theme={null}
# See https://github.com/aspect-build/aspect-gazelle/releases for the latest version.
bazel_dep(name = "aspect_gazelle_prebuilt", version = "0.0.21")
```

Then declare a gazelle target, conventionally at `//tools/gazelle`, selecting the languages your repo uses:

```python theme={null}
load("@aspect_gazelle_prebuilt//:def.bzl", "aspect_gazelle")

aspect_gazelle(
    name = "gazelle",
    languages = ["proto", "python", "js"],
)
```

Omit `languages` entirely to get the default set (`visibility_extension`, `proto`, `starlark`, `python`, `js`). The valid language keys are `buf`, `cc`, `go`, `js`, `kotlin`, `orion`, `proto`, `python`, `starlark`, and `visibility_extension`.

That target is what `aspect gazelle` runs by default. Crucially, this is the binary that interprets the Starlark (`.axl`) extensions we write later in the course — building from source (below) cannot run them.

Enabling the `go` language requires some extra `repo_config` and `go_deps` wiring — see the [`aspect_gazelle_prebuilt` README](https://github.com/aspect-build/aspect-gazelle/blob/main/prebuilt/README.md#rules_go-go_deps-must-still-come-from-gazelle) for the details.

**Why prefer the prebuilt binary over building from source?**

* No Go toolchain download and no first-run compile — developers fetch a cached artifact instead.
* It bundles all the common, well-written language extensions, including support for the orion Gazelle language for writing your own extensions in Starlark/AXL.
* It avoids the bootstrapping trap: a broken `BUILD` file referenced by your gazelle binary's `load` statements can otherwise prevent gazelle from compiling, and therefore from fixing that file.

## Building from source

```python theme={null}
load("@bazel_gazelle//:def.bzl", "gazelle", "gazelle_binary")

gazelle_binary(
    name = "my_gazelle_binary",
    # NB: order matters!
    languages = [
        "@bazel_gazelle//language/proto",  # Built-in rule from gazelle for Protos.
         # Any languages that depend on Gazelle's proto plugin must come after it.

        "@bazel_gazelle//language/go",  # Built-in rule from gazelle for Golang.

        "@rules_python//gazelle",  # Use gazelle from rules_python.
        
        "//bazel/my/extension", # A custom first-party extension, a `go_library`
    ],
    visibility = ["//visibility:public"],
)

# gazelle:prefix example.com/project
gazelle(
    name = "gazelle",
    gazelle = ":my_gazelle_binary",
)
```

## Drawbacks of building from source

* **Bootstrapping trap** — broken `BUILD` files referenced (even transitively) by `load` statements prevent Gazelle from compiling, so it can't fix the very files it needs to run.
* **Slow cold starts** — Bazel adds latency for analysis-cache rebuilds and external-repo fetches; a prebuilt artifact skips both.
* **Rebuild on every extension change** — any edit to a first-party Go extension forces all developers to recompile the binary.
* **cgo portability** — the Go toolchain is hermetic under Bazel but cgo is not (without extra work). Extensions that need it (such as rules\_python) may not compile on all developer machines. See [this PR](https://github.com/bazelbuild/rules_python/pull/2320).
* **Unnecessary Go toolchain** — repos without Go code still pull down the Go toolchain and all its complexity.

## Checking on CI

CI steps should verify that the repository is “gazelle-clean” in case developers haven’t run the tool.

Pass `with_check = True` to `aspect_gazelle()` to generate a companion `<name>.check` target that runs Gazelle in `diff` mode — it makes no changes, prints a diff of what would change, and exits non-zero if any `BUILD` file is stale:

```python theme={null}
aspect_gazelle(
    name = "gazelle",
    languages = ["proto", "python", "js"],
    with_check = True,
)
```

```sh theme={null}
bazel run //tools/gazelle          # developers: update BUILD files
bazel run //tools/gazelle.check    # CI: fail if BUILD files are stale
```

Aspect Workflows has this feature built-in! Check out [Aspect Workflows](/platform/build-file-generation)