# Enable Experimental Background Indexing

> [!IMPORTANT]
> Background indexing is enabled by default in Swift 6.1 toolchains and above. This guide only refers to Swift 6.0 toolchains.

Background indexing in SourceKit-LSP is enabled by default in Swift 6.1 toolchains and is available as an experimental feature for Swift 6.0 toolchains.

## Behavior Without Background Indexing

With background indexing disabled, SourceKit-LSP does not update its global index in the background or build Swift modules in the background. Thus, a lot of cross-module or global functionality is limited if the project hasn't been built recently. For example, consider two modules: `Lib` and `Exec`, where `Exec` depends on `Lib`: Without background indexing, if a function is added to `Lib`, completion/jump to definition/etc in `Exec` would not be able to see that function until after a build. Background indexing solves that issue.

## Set Up

1. Install the Swift 6.0 toolchain or install [Xcode 16](https://developer.apple.com/xcode/).
2. Enable the experimental `background-indexing` feature by creating a [configuration file](Configuration%20File.md) at `~/.sourcekit-lsp/config.json` with the following contents:
```json
{
  "backgroundIndexing": true,
  "backgroundPreparationMode": "enabled"
}
```

## Known issues

- Background Indexing is only supported for SwiftPM projects [#1269](https://github.com/swiftlang/sourcekit-lsp/issues/1269), [#1271](https://github.com/swiftlang/sourcekit-lsp/issues/1271)
- If you change a function in a way that changes its USR but keeps it API compatible (such as adding a defaulted parameter), references to it will be lost and not re-indexed automatically [#1264](https://github.com/swiftlang/sourcekit-lsp/issues/1264)
  - Workaround: Make some edit to the files that had references to re-index them
- The index build is currently completely separate from the command line build generated using `swift build`. Building *does not* update the index (break your habits of always building!) [#1270](https://github.com/swiftlang/sourcekit-lsp/issues/1270)
- The initial indexing might take 2-3x more time than a regular build [#1262](https://github.com/swiftlang/sourcekit-lsp/issues/1262), [#1268](https://github.com/swiftlang/sourcekit-lsp/issues/1268)

## Filing issues

If you hit any issues that are not mentioned above, please [file a GitHub issue](https://github.com/swiftlang/sourcekit-lsp/issues/new/choose) and attach the following information, if possible:
- A diagnostic bundle generated by running `path/to/sourcekit-lsp diagnose`.
- Your project including the `.build` folder, if possible.
