biome format --write: Apply Formatting in Place
biome format --write applies the formatter and saves the result back to disk.
This is the local and pre-commit form of the formatter. Keep it out of CI verification jobs, where an unwritten check should fail instead.
What it does
biome format --write formats the given files and writes the changes in place. Combined with --staged or --changed it limits the work to files that git reports as staged or changed, which is what pre-commit hooks use.
Common usage
npx @biomejs/biome format --write ./src
# only files staged in git (pre-commit)
npx @biomejs/biome format --write --staged
# only files changed against the base branch
npx @biomejs/biome format --write --changedOptions
| Flag | What it does |
|---|---|
| --write | Write formatted output to disk |
| --staged | Only process files staged in git |
| --changed | Only process files changed against the VCS base |
| --since=<ref> | With --changed, compare against the given ref |
| --files-ignore-unknown=true | Do not error on file types Biome cannot handle |
In CI
In a verification pipeline run format without --write so an unformatted file fails the job. Reserve --write for local hooks. --staged and --changed both require the vcs section in biome.json to be enabled.
Common errors in CI
"The configuration of vcs is invalid" or "--staged needs the VCS integration" means vcs.enabled is not true with clientKind "git". If --write reports no changes when you expect some, the files may be ignored by files.ignore or by .gitignore when vcs.useIgnoreFile is true.