# .bazelproject file reference

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com/help/idea/llms.txt).

A [project view file](bazel-project-view.html) is split into named sections and uses a Python-like format with two spaces indentation.

## File and section syntax

* The content after a `#` and up to a newline is treated as comment.

* Section headers start at the beginning of a line and use the `name: body` or `name body` format. Both a space or a colon are acceptable after a section name.

* Section body extends until the next section header.

## Section types

All named sections belong to one of the following types:

* Single value sections: one value (Boolean, Int, Path, or String), for example: ```TEXT derive_targets_from_directories: true import_depth 2 ```

* List sections: multiple values separated with a space or a newline, for example: ```TEXT build_flags: --config=ci --cxxopt=-O2 ```

* Excludable list sections: multiple values separated with a space or a newline; entries starting with `-` are excluded. For example: ```TEXT targets: //app:all -//app:tests ```

## Repeating sections

Sections can appear multiple times. If that happens, the following resolution rules apply:

* Single-value sections: the last occurrence wins.

* List sections: the sections are merged in the order of appearance.

* Excludable list sections: like with regular list sections, both included and excluded lists are merged in the order of appearance.

## Imports

A project view can import other project views using `import` and `try_import`.

* `import path/to/file.bazelproject` Required import. If the file cannot be found, the project view is not considered valid.

* `try_import path/to/optional.bazelproject` Optional import. If the file cannot be found, the project view is still valid without importing the other project view.

IntelliJ IDEA parses all `import` entries first, then all `try_import` entries in the order they appear in the file. After the imports, the current file's own sections are processed.

You can use multiple imports in a project view. In this case, the imported list sections (for example, `targets`) are merged and single-value sections (for example, `bazel_binary` override the previously encountered ones.

## Sections reference

Below is the complete list of available sections grouped by type. For the list of section types and their syntax, refer to the [Section types](#section_types) chapter.

### Excludable list sections

targets (List<Path>)
: A set of Bazel targets to include in the import. Supports the recursive wildcard for packages (`/...`). The more targets you have, the slower your IDE experience might be.
:
:
:
: Example:
:
:
:
:
: ```
: targets:
: //install/src/main/kotlin/org/jetbrains/bazel/install
: //executioncontext/projectview/...
: -//executioncontext/projectview/src/main/kotlin/org/jetbrains/bazel/projectview/parser/...
: ```

directories (List<Path>)
: The directories to be mapped into Bazel targets. Can be used with [derive_targets_from_directories](#derive_targets_from_directories) to automatically discover the relevant targets by scanning the specified directories.
:
:
:
: Example:
:
:
:
:
: ```
: directories:
: install/src/main/kotlin/org/jetbrains/bazel/install
: executioncontext/projectview/
: -executioncontext/projectview/src/main/kotlin/org/jetbrains/bazel/projectview/parser
: ```

### List sections

build_flags (List<String>)
: A set of Bazel flags that is passed with all Bazel command invocations. By default, no flags are passed.
:
:
:
: Example:
:
:
:
:
: ```
: build_flags:
: --define=ij_product=intellij-latest
: ```

sync_flags (List<String>)
: A set of Bazel flags that is passed with Bazel command invocations during sync. By default, no flags are passed.
:
:
:
: Example:
:
:
:
:
: ```
: sync_flags:
: --define=ij_product=intellij-latest
: ```

test_flags (List<String>)
: To be supported in future releases.

debug_flags (List<String>)
: A set of Bazel flags that is passed to `bazel run` in debug mode.
:
:
:
: Example:
:
:
:
:
: ```
: debug_flags:
: --cxxopt=-g
: ```

enabled_rules (List<String>)
: Explicitly declares which external Bazel rulesets should be enabled for your project and overrides auto-detection, which can be incomplete for some setups.
:
:
:
: Example:
:
:
:
:
: ```
: enabled_rules:
: rules_java
: rules_kotlin
: ```

import_run_configurations (List<Path>)
: A list of XML files to import as run configurations during Bazel sync.
:
:
:
: Example:
:
:
:
:
: ```
: import_run_configurations:
: tools/intellij/run_application.xml
: tools/intellij/run_tests.xml
: ```
:
:
:
: > **Note:**
: > Run configurations from Google's Bazel plugin are converted to the new format automatically upon import.
:
:
:
: > **Tip:**
: > For exporting run configurations to XML, refer to [Share run/debug configurations](run-debug-configuration.html#share-configurations)

java_source_root_optimization_patterns (List<String>)
: Specifies glob patterns indicating source directories eligible for optimized package inference. This section is used together with [java_source_root_optimization_enable](#java_source_root_optimization_enable).
:
:
:
: The package of the source files, whose paths match at least one of those patterns, is derived using bulk optimization. The package information for other source files is read from each individual file.
:
:
:
: Default patterns: `src/main/java`, `src/test/java`, `src/main/kotlin`, `src/test/kotlin`, `src/java`, and `src/kotlin`.
:
:
:
: `*` applies the optimization to all source directories.
:
:
:
: Example:
:
:
:
:
: ```
: java_source_root_optimization_patterns:
: src/main/kotlin
: ```

python_code_generator_rule_names (List<String>)
: Specifies which Bazel rule kinds should be treated as Python code generators.
:
:
:
: Example:
:
:
:
:
: ```
: python_code_generator_rule_names:
: my_py_codegen_rule
: another_py_codegen
: ```

index_additional_files_in_directories (List<String>)
: Specifies filenames or glob patterns for files to be indexed by IntelliJ IDEA, in addition to the sources, resources, and libraries already defined by targets.
:
:
:
: For faster indexing, IntelliJ IDEA only indexes files that belong to Bazel targets. This can exclude some files, such as `*.xml` configs, `package.json`, or other non-source files that do not directly appear in the resource sections of a target. This means they will get slower search, and some IntelliJ IDEA's features, including the navigation to definitions and usages, will not work for them.
:
:
:
: The patterns from this section are combined with a set of built-in defaults that are always indexed:
:
:
:
: * `WORKSPACE` / `WORKSPACE.bazel` files
:
: * `BUILD` / `BUILD.bazel` files
:
: * `MODULE.bazel`
:
:
:
: Example:
:
:
:
:
: ```
: index_additional_files_in_directories:
: *.xml
: package.json
: ```
:
:
:
: > **Note:**
: > This section does not apply when [index_all_files_in_directories](#index_all_files_in_directories) is `true`

### Single-value sections

bazel_binary (Path)
: Path to Bazel, which will be used on the server for operations such as building a project or executing a Bazel query. If not specified, the server will use the binary from the `$PATH` variable.
:
:
:
: Example:
:
:
:
:
: ```
: bazel_binary: /usr/local/bin/bazel
: ```

derive_targets_from_directories (Boolean)
: Specifies if targets should be derived from the directories in the `directories` section. By default, targets are not derived (`false`), but the directories are not excluded from the project view.
:
:
:
: Example:
:
:
:
:
: ```
: derive_targets_from_directories: true
: ```

import_depth (Int)
: Specifies how many levels of Bazel targets' dependencies should be imported as modules. Only the targets that are present in the workspace are imported. You can use a negative value to import all transitive dependencies. The default value is `-1`, meaning that all transitive context is included.
:
:
:
: Example:
:
:
:
:
: ```
: import_depth: 1
: ```

allow_manual_targets_sync (Boolean)
: Allow syncing targets tagged as manual. By default (`false`), manual-only targets are skipped.
:
:
:
: Example:
:
:
:
:
: ```
: allow_manual_targets_sync: true
: ```

ide_java_home_override (Path)
: Override `JAVA_HOME` used by IntelliJ IDEA for Java targets during sync and IDE operations. It overrides the JDK that would otherwise be inferred from Bazel’s Java toolchains/runtime. Bazel itself will still build with its configured toolchain; this override is IDE-only.
:
:
:
: Example:
:
:
:
:
: ```
: ide_java_home_override:
: /Users/me/Library/Java/JavaVirtualMachines/jbr-21
: ```

shard_sync (Boolean)
: Allows splitting Bazel sync/build into smaller batches, also referred to as shards, instead of executing a single sync/build. This helps avoid Bazel running out of memory and reduce issues like overly long command lines when syncing large sets of targets. The default is `false` because of a [potential memory leak issue](https://github.com/bazelbuild/bazel/issues/19412) with Bazel.
:
:
:
: Example:
:
:
:
:
: ```
: shard_sync: true
: ```

target_shard_size (Int)
: Specifies the number of targets to be built in a shard. The default is `1000`
:
:
:
: Example:
:
:
:
:
: ```
: target_shard_size: 500
: ```

shard_approach (String)
: Specifies the strategy used to shard the list of original targets. Used in combination with [shard_sync](#shard_sync). The default is `QUERY_AND_SHARD`.
:
:
:
: The following values are possible:
:
:
:
: * `EXPAND_AND_SHARD`: expand wildcard targets to package targets, query single targets, then shard to batches
:
: * `QUERY_AND_SHARD`: query single targets from the given list of targets without expanding, then shard to batches
:
: * `SHARD_ONLY`: split unexpanded wildcard targets into batches
:
:
:
: Example:
:
:
:
:
: ```
: shard_approach: EXPAND_AND_SHARD
: ```

gazelle_target (String)
: Specifies whether IntelliJ IDEA should run a Gazelle target automatically at the start of each Bazel sync. This updates or generates BUILD files for the directories included in the project view before IntelliJ IDEA collects targets and indexes sources.
:
:
:
: Example:
:
:
:
:
: ```
: gazelle_target: //tools/gazelle:gazelle
: ```

index_all_files_in_directories (Boolean)
: Specifies whether IntelliJ IDEA should index all files under the directories listed in the `directories` section, regardless of whether the files belong to a Bazel target. This allows for faster search and navigation for non-target sources, docs, or scripts, but indexing itself can be slow and memory-heavy in monorepos or large projects. The default is `false`.
:
:
:
: Example:
:
:
:
:
: ```
: index_all_files_in_directories: true
: ```

import_ijars (Boolean)
: Specifies whether to prefer interface/header jars (ijars) for JVM libraries instead of full jars during import. Interface/header jars contain only public API class stubs and not the full bytecode. This can reduce the size of the index and improve import performance at the cost of navigation to library implementations and false-positives in some of the IDE warnings. The default is `false`.
:
:
:
: Example:
:
:
:
:
: ```
: import_ijars: true
: ```

java_source_root_optimization_enable (Boolean)
: Enables Java source root optimization.
:
:
:
: Without this optimization, IntelliJ IDEA gets package information for Java, Kotlin, or Scala sources by reading the corresponding declarations in each file.
:
:
:
: In large monorepos, reading package information for every source file can be slow. With `java_source_root_optimization_enable`, IntelliJ IDEA uses patterns specified in [java_source_root_optimization_patterns](#java_source_root_optimization_patterns) and resolves files' packages in bulk, reducing I/O overhead. The default is `false`.
:
:
:
: Example:
:
:
:
:
: ```
: java_source_root_optimization_enable: true
: ```

run_config_run_with_bazel (Boolean)
: Controls whether run configurations execute using Bazel (`bazel run`/`bazel test`) or through [--script_path](https://bazel.build/reference/command-line-reference#run-flag--script_path).
:
:
:
: When enabled, Bazel handles the full execution, which allows you to benefit from Bazel's test result caching and remote build execution (RBE). The trade-off is that Bazel acquires a workspace lock during execution, so you cannot run multiple run configurations in parallel.
:
:
:
: When disabled, IntelliJ IDEA compiles the target through Bazel but launches the resulting binary directly, bypassing the Bazel lock.
:
:
:
: > **Note:**
: > This setting is ignored when debugging: debug sessions never use Bazel execution.
:
:
:
: The default is `true`.
:
:
:
: Example:
:
:
:
:
: ```
: run_config_run_with_bazel: false
: ```

derive_instrumentation_filter_from_targets (Boolean)
: Specifies whether to compute and add `--instrumentation_filter` that includes the Bazel packages of all imported targets. When `false`, the instrumentation filter is not added, or you can specify it using `.bazelrc`. For example, `coverage --instrumentation_filter="^//"`. The default is `true`.
:
:
:
: Example:
:
:
:
:
: ```
: derive_instrumentation_filter_from_targets: false
: ```

