Building with Bazel

This page walks through building IREE from source using the Bazel build system.

Warning

Bazel build support is primarily for internal project infrastructure. We strongly recommend using CMake instead.

Our Bazel configuration is also only tested on Linux. Windows and macOS may be unstable.

Prerequisites

Linux macOS Windows

1. Recommended: Install bazelisk to automatically use the correct Bazel version from .bazelversion:

   # Via Go (if installed)
   go install github.com/bazelbuild/bazelisk@latest
   
   # Or download binary from GitHub releases
   

   Alternative: Install Bazel 7.3.1 manually by following the official docs.

2. Install a compiler such as Clang (GCC is not fully supported).

   sudo apt install clang
   

   Set environment variables for Bazel:

   export CC=clang
   export CXX=clang++
   

3. Install Python build requirements:

   python -m pip install -r runtime/bindings/python/iree/runtime/build_requirements.txt
   

1. Install Homebrew:

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
   

2. Recommended: Install bazelisk to automatically use the correct Bazel version from .bazelversion:

   brew install bazelisk
   

   Alternative: Install Bazel 7.3.1 manually by following the official docs or via Homebrew:

   brew install bazel
   

3. Install Python build requirements:

   python -m pip install -r runtime/bindings/python/iree/runtime/build_requirements.txt
   

Tip

You can simplify installation by using a package manager like Scoop or Chocolatey.

1. Recommended: Install bazelisk to automatically use the correct Bazel version from .bazelversion:

   # Via Scoop
   scoop install bazelisk
   
   # Via Chocolatey
   choco install bazelisk
   
   # Or download binary from GitHub releases
   

   Alternative: Install Bazel 7.3.1 manually by following the official docs.

   Also install MSYS2 by following Bazel's documentation.

2. Install Python3 (docs here) and Python build requirements:

   python -m pip install -r runtime/bindings/python/iree/runtime/build_requirements.txt
   

3. Install the full Visual Studio or "Build Tools For Visual Studio" from the downloads page then set the BAZEL_VS environment variable:

   > $env:BAZEL_VS = "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools"
   

Quickstart: clone and build

TL;DR - Copy and paste this to get started:

# Clone and setup
git clone https://github.com/iree-org/iree.git
cd iree
git submodule update --init
python -m pip install -r runtime/bindings/python/iree/runtime/build_requirements.txt

# Add tools to PATH (from repo root)
export PATH="$PWD/build_tools/bin:$PATH"

# Configure once
iree-bazel-configure

# Build and test
iree-bazel-build //tools:iree-compile
iree-bazel-test //...

Building with CUDA?

Enable GPU drivers before configure:

IREE_HAL_DRIVER_CUDA=ON iree-bazel-configure

Requires CUDA toolkit installed separately.

Driver configuration is sticky

Re-run iree-bazel-configure whenever you change IREE_HAL_DRIVER_* settings.

Working with Claude Code?

All iree-bazel-* tools provide machine-readable documentation via --agent_md:

# Generate documentation for Claude
iree-bazel-configure --agent_md >> CLAUDE.local.md

This appends concise tool documentation to your local Claude instructions, teaching Claude how to use the iree-bazel-* tools in your project.

Detailed steps

1. Clone the repository:

   git clone https://github.com/iree-org/iree.git
   cd iree
   git submodule update --init
   

   Windows: Short paths

   Clone to a short path like C:\projects\ to avoid issues with Windows maximum path lengths (260 characters).

2. Install Python dependencies:

   python -m pip install -r runtime/bindings/python/iree/runtime/build_requirements.txt
   

3. Add wrapper tools to PATH:

   export PATH="$PWD/build_tools/bin:$PATH"
   

   The iree-bazel-* wrapper tools simplify common workflows and provide sensible defaults for local development. Run from the IREE repository root.

4. Configure once per worktree:

   iree-bazel-configure
   

   This detects your platform/compiler and creates configuration files (configured.bazelrc and user.bazelrc). Re-run this command to change driver settings or after major environment changes.

5. Build and test:

   # Build specific targets
   iree-bazel-build //tools:iree-compile
   
   # Run all tests
   iree-bazel-test //...
   
   # Run tests in a specific directory
   iree-bazel-test //runtime/...
   

Build artifacts are under the bazel-bin/ directory, test logs under bazel-testlogs/.

Local development configuration

For faster local development iteration, use the --config=localdev flag:

bazel build --config=localdev //tools/...
bazel test --config=localdev //runtime/...

Note

The iree-bazel-* wrapper tools use --config=localdev by default, so you don't need to specify it manually.

This enables several optimizations:

• Skymeld (merged analysis/execution phases for faster multi-target builds)
• Ramdisk sandbox on Linux (reduces I/O bottleneck with many CPU cores)

The localdev config is defined in build_tools/bazel/iree.bazelrc and works on all platforms.

Optional user.bazelrc

Note

iree-bazel-configure creates user.bazelrc automatically with platform-specific defaults (including disk cache location). You can customize it further as shown below.

You can put a user.bazelrc at the root of the repository for personal customizations (ignored by git). For example:

Linux macOS Windows

# Always use localdev optimizations
build --config=localdev

# Use --config=debug to compile IREE and LLVM without optimizations
# and with assertions enabled.
build:debug --config=asserts --compilation_mode=opt '--per_file_copt=iree|llvm@-O0' --strip=never

# Use --config=asserts to enable assertions. This has to be done globally:
# Code compiled with and without assertions can't be linked together (ODR violation).
build:asserts --compilation_mode=opt '--copt=-UNDEBUG'

# Always use localdev optimizations
build --config=localdev

# Use --config=debug to compile IREE and LLVM without optimizations
# and with assertions enabled.
build:debug --config=asserts --compilation_mode=opt '--per_file_copt=iree|llvm@-O0' --strip=never

# Use --config=asserts to enable assertions. This has to be done globally:
# Code compiled with and without assertions can't be linked together (ODR violation).
build:asserts --compilation_mode=opt '--copt=-UNDEBUG'

# Always use localdev optimizations
build --config=localdev

# Debug config for Windows
build:debug --compilation_mode=dbg --copt=/O2 --per_file_copt=iree@/Od --strip=never

Bazel Wrapper Tools

IREE provides wrapper scripts in build_tools/bin/ that simplify common Bazel workflows:

Setup:

# Add to your PATH (in ~/.bashrc or similar)
export PATH="$PATH:/path/to/iree/build_tools/bin"

Available tools:

• iree-bazel-configure - Initial Bazel setup (run once per worktree)
• iree-bazel-build [target] - Build with optimized defaults (supports -w watch mode)
• iree-bazel-test [target] - Run tests with configured drivers (supports -w watch mode)
• iree-bazel-run <target> [-- args] - Build and execute from current directory (supports -w watch mode)
• iree-bazel-query <expr> - Query the build graph
• iree-bazel-try <file> - Compile/run C++ snippets without BUILD files
• iree-bazel-fuzz <target> - Run fuzzer with corpus management

Examples:

# Configure with CUDA support
IREE_HAL_DRIVER_CUDA=ON iree-bazel-configure

# Build compiler tools
iree-bazel-build //tools:iree-compile

# Run all tests (using configured drivers)
iree-bazel-test //...

# Reconfigure to enable multiple drivers
IREE_HAL_DRIVER_CUDA=ON IREE_HAL_DRIVER_VULKAN=ON iree-bazel-configure

# Run tool from current directory
iree-bazel-run //tools:iree-compile -- input.mlir -o output.vmfb

# Quick C++ experiment
iree-bazel-try -e '#include "iree/base/api.h"
int main() { return iree_status_is_ok(iree_ok_status()) ? 0 : 1; }'

Watch mode:

Add -w or --watch to automatically rebuild/retest on file changes:

# Rebuild on changes
iree-bazel-build -w //tools:iree-compile

# Rerun tests on changes (great for TDD)
iree-bazel-test -w //runtime/src/iree/base:status_test

# Rebuild and restart binary on changes
iree-bazel-run -w //tools:iree-opt -- input.mlir

Watch mode uses ibazel which must be installed separately:

go install github.com/bazelbuild/bazel-watcher/cmd/ibazel@latest

Bazel server lock behavior

Watch mode holds the Bazel server lock while the binary runs (necessary for ibazel to control process lifecycle). Normal mode releases the lock after building, allowing parallel builds in other shells.

Environment variables:

• IREE_BAZEL_CACHE_DIR: Bazel disk cache location (default: ~/.cache/bazel-iree)
• IREE_HAL_DRIVER_*: Enable/disable HAL drivers (configure-time, matches CMake)
  • IREE_HAL_DRIVER_CUDA=ON: Enable CUDA driver
  • IREE_HAL_DRIVER_VULKAN=ON: Enable Vulkan driver
  • Values: ON/YES/TRUE/Y/1 or OFF/NO/FALSE/N/0
• IREE_FUZZ_CACHE: Fuzzer corpus cache (default: ~/.cache/iree-fuzz-cache)
• IREE_FUZZ_CORPUS: Fuzzer dictionaries (default: ~/.cache/iree-fuzz-corpus)

Tips:

• Add -v flag to see the exact Bazel command being executed
• Wrappers use --config=localdev by default for faster local iteration
• Run <tool> --help for detailed usage information

Advanced: Under the Hood

Wrapper → Raw Bazel mapping

The wrapper tools are thin shells around standard Bazel commands. Here's what they do:

Wrapper	Equivalent Raw Command
iree-bazel-build //foo	bazel build --config=localdev //foo
iree-bazel-build -w //foo	ibazel build --config=localdev //foo
iree-bazel-test //...	bazel test --config=localdev //...
iree-bazel-test -w //...	ibazel test --config=localdev //...
iree-bazel-run //foo	Build + exec (releases lock)
iree-bazel-run -w //foo	ibazel run --run_under="cd $PWD && " //foo
iree-bazel-configure	python3 configure_bazel.py + create user.bazelrc

Debugging wrappers: Use -v or --verbose flag to print the exact Bazel command being executed.

For CI/scripts: Raw bazel commands work fine. Wrappers are optional helpers for local development.

Configuration files

• configured.bazelrc - Written by configure_bazel.py (platform detection, driver settings)
• user.bazelrc - Created by iree-bazel-configure (disk cache location, custom configs)
• build_tools/bazel/iree.bazelrc - Main IREE configuration (localdev, GPU, etc.)

All three files are loaded automatically by Bazel in this order.

What's next?

Take a Look Around

Build all of IREE's 'tools' directory:

bazel build //tools/...

Check out what was built:

ls bazel-bin/tools/
./bazel-bin/tools/iree-compile --help

Translate a MLIR file and execute a function in the compiled module:

# iree-run-mlir <compiler flags> [input.mlir] <runtime flags>
$ ./bazel-bin/tools/iree-run-mlir \
  --iree-hal-target-device=local \
  --iree-hal-local-target-device-backends=vmvx \
  --print-mlir \
  ./samples/models/simple_abs.mlir \
  --input=f32=-2