# swift-format: Swift's own formatter, and how to run it

> swift-format is the formatting technology behind SourceKit-LSP, shipped in the Swift toolchain since Swift 6 and also installable via Homebrew. It formats and lints Swift source, but the project states that no default style guidelines have been proposed yet.

**swiftlang/swift-format** — Formatting technology for Swift source code

- Repository: https://github.com/swiftlang/swift-format
- Stars: 2,960 · Forks: 294
- Language: Swift
- License: Apache-2.0
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/swiftlang-swift-format

## What swift-format is for, and who it is actually aimed at

swift-format provides formatting technology for SourceKit-LSP and what the README calls the building blocks for doing code formatting transformations. That phrasing points at two distinct audiences. The first is anyone who wants a Swift file reformatted: a command line tool that reads Swift source and writes it back out. The second is tool authors who want to embed formatting in an editor or another program, which the README describes as linking the package into an application as a Swift Package Manager dependency and invoking it through an API. Those two uses pull in different directions. A CLI user cares about the visible output and the exit code. An integrator cares about the library surface and whether it can be called repeatedly inside a long-running process. The README covers both but gives the CLI the bulk of the space.

The project is honest about a gap that matters more than any feature list. A note in the README states that no default Swift code style guidelines have yet been proposed, that the style currently applied is just one possibility, and that the code is provided so it can be tested on real-world code and experiments can be made by modifying it. Read that literally: the formatting you get out of the box is a working example, not an agreed standard. If your team is looking for the one true Swift style, this project does not claim to be it.

## How the formatter and linter are wired together

The package exposes a single executable with subcommands. The general invocation is swift-format [SUBCOMMAND] [OPTIONS...] [FILES...]. Two subcommands matter in daily use. format rewrites source, and lint checks source and prints diagnostics to standard error for any violations detected. Writing format explicitly is optional: the README says it is the default behavior when no other subcommand is given.

Both subcommands accept the same common options, which is a deliberate design choice. The README lists --assume-filename <path>, which supplies the filename used in diagnostics when input comes from standard input instead of a file path, defaulting to <stdin>. It also lists --color-diagnostics and --no-color-diagnostics, with color enabled by default when standard error is connected to a terminal and disabled otherwise, so redirected output stays clean.

The split between format and lint is where the design gets interesting. lint does not modify files; it reports. By default, lint warnings do not cause a failing exit code. Only fatal errors, such as trying to lint a file that does not exist, fail the run. The -s/--strict flag changes that, making lint warnings produce a non-zero exit code. That distinction is what makes the tool usable in two very different places: a developer running it locally can see warnings without their command failing, while a continuous integration job can add --strict and fail the build on the same warnings. The formatting side has its own asymmetry. Without -i/--in-place, format prints results to standard output rather than touching the input files, and the README warns that in-place mode makes no backup of the original file before it is overwritten.

## Installing swift-format and running a first format and lint

There are three documented routes to get the tool. The first is the Swift toolchain itself: the README states that Swift 6, included with Xcode 16, and above include swift-format, invoked as swift format with a space instead of a dash. To locate the binary inside Xcode, the README gives xcrun --find swift-format. The second is Homebrew, with a single command. The third is building from source.

If you have a recent toolchain, the built-in command is the shortest path, and the README describes invoking it as swift format with a space instead of a dash:

```sh
swift format
```

If that resolves, you already have a formatter and do not need to install anything. If it does not, Homebrew is the next step:

```sh
brew install swift-format
```

Building from source is the route the README documents in full, and it pins a version explicitly:

```sh
VERSION=510.1.0  # replace this with the version you need
git clone https://github.com/swiftlang/swift-format.git
cd swift-format
git checkout "tags/$VERSION"
swift build -c release
```

The README notes that this checkout leaves the repository in a detached HEAD state, which it says is fine if building and running the tool is all you want to do. After the build, the executable sits at .build/release/swift-format. The README also offers swift test --parallel as a way to confirm the build works against your toolchain, recommending --parallel because of the large number of tests.

For a first real use, the README gives the general invocation syntax, and the format subcommand is the default when no other subcommand is given:

```sh
swift-format [SUBCOMMAND] [OPTIONS...] [FILES...]
```

Without -i/--in-place, the formatted result is printed to standard output and the original file is untouched, so you can inspect it before committing to the change. Once you are satisfied, add -i to overwrite in place, remembering that the README states no backup of the original file is made. To check a file rather than change it, use the lint subcommand, and add the --strict option if you want lint warnings to cause a non-zero exit code:

```sh
swift-format lint [OPTIONS...] [FILES...]
```

The README points out that each subcommand has its own help text, reachable with the --help flag after the subcommand name, for example swift-format lint --help.

## Version matching is the sharpest edge in this project

The README devotes an entire section to matching swift-format to your Swift version, and the reason is structural. Before Swift 5.8, swift-format depended on SwiftSyntax versions that used a standalone parsing library distributed as part of the Swift toolchain. The major and minor version components of swift-format and SwiftSyntax had to be identical, and those components had to match the installed toolchain, which is why the README carries a table mapping Xcode releases to branch and tag names. Xcode 13.3 with Swift 5.6 needs swift-format 0.50600.0, and so on down to Xcode 11.0 through 11.3 with Swift 5.1 on the swift-5.1-branch.

As of Swift 5.8, the parser was rewritten in Swift and dropped its dependencies on Swift toolchain libraries, which the README says allows swift-format to be built, developed and run with any Swift version that can compile it. That decoupling is real, but the README immediately qualifies it: earlier versions of swift-format will still not recognize new syntax added in later versions of the language and parser. So on a current toolchain you can build the formatter freely, yet the formatter you build is only as syntax-aware as the release you checked out. The version numbering also changed to match SwiftSyntax, which is why the 5.8 release is 508.0.0 rather than 0.50800.0. If you find old build scripts referencing the older scheme, that is the reason.

## Where swift-format is the wrong tool

The clearest limitation is stated by the project itself: no default Swift code style guidelines have been proposed, and the applied style is one possibility among many. A formatter without an agreed style is a formatter whose output your team will argue about. If your organization expects a published, stable rule set that reviewers can cite, swift-format does not supply one, and the README frames the current style as something to be tested and modified rather than adopted wholesale.

The second limitation is the in-place behavior. -i/--in-place overwrites input files and, per the README, makes no backup of the original. There is no documented undo, no rollback flag, and no dry-run mode described in the README beyond the default of printing to standard output. The practical consequence is that in-place formatting belongs inside a version-controlled working tree, where git holds the previous state, and not in any context where the file is the only copy.

The third is version drift in the other direction. Because a given swift-format release only understands syntax up to its own SwiftSyntax version, a formatter pinned for an older toolchain can fail on newer language constructs. The README is explicit that earlier versions will not recognize syntax added later. If you are on an older Xcode, you are choosing between a formatter that matches your toolchain and a formatter that understands your source.

## How it differs from SwiftLint

The comparison that people search for is swift-format versus SwiftLint, and the two are not the same kind of tool. swift-format is a formatter first: its format subcommand rewrites source, and its lint subcommand reports style violations. Both subcommands share the same configuration and the same options, and the README presents lint as a check over the same style rules the formatter applies. The purpose is consistency of layout and syntax presentation.

SwiftLint is a linter in the traditional sense, oriented around rules about code structure and patterns rather than canonical whitespace and line breaking. The README of swift-format does not compare itself to SwiftLint at all, so any claim about which rules each one covers would be guesswork. What can be said from what the README documents is narrower and more useful: swift-format's lint output is derived from the same style engine that produces its formatted output, so a violation it reports is something its own format subcommand would fix. A linter that does not own a formatter cannot make that claim. If your goal is that running a tool leaves the code in the state the tool approves of, the formatter-plus-linter pairing is the relevant property. If your goal is catching patterns that have nothing to do with layout, that is a different job.

## Maintenance, licensing and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-22, with a 604.0.0 release on 2026-09-16 and a 603.0.0 release on 2026-06-30 before it. Releases are numbered to track SwiftSyntax, so upgrading the formatter is coupled to upgrading the Swift toolchain you build it with. That is the upgrade cost in one sentence: you rarely move swift-format alone.

The licence is Apache-2.0, and the repository carries a LICENSE.txt at its root along with a .license_header_template and a .licenseignore, which suggests new files are expected to carry a header. Apache-2.0 is a permissive licence that permits commercial and closed-source use, but it also includes an explicit patent grant and requires that notices be preserved. Whether that fits your distribution model is a question for your own legal review, not something this article can settle.

One more repository detail is worth knowing before you configure anything: there is a .swift-format file at the top level. The project formats itself with its own tool, and that file is where its configuration lives. Reading it is the fastest way to see what a real configuration looks like, and it is a more reliable starting point than guessing at option names.

## Conclusion

Adopt swift-format if your project already builds with a recent Swift toolchain and you want a formatter that is part of that toolchain rather than an external dependency; the README's own warning that no default style guidelines have been proposed means you should treat the built-in style as a starting point to be edited, not a standard. Do not adopt it if you are pinned to Swift 5.7 or earlier, where the README requires checking out a release tag or branch matching your installed toolchain, or if you need a formatter whose rules are settled and documented as a specification. Before rolling it out across a repository, run swift-format lint --strict on a sample of files to see how many violations the current style produces, and read the .swift-format file at the repository root to see what the project itself configures.

## FAQ

### How do I install swift-format?

Swift 6, included with Xcode 16, and later ship swift-format in the toolchain, where you invoke it as swift format with a space instead of a dash. Otherwise the README gives brew install swift-format, or building from source by cloning the repository, checking out a version tag, and running swift build -c release.

### How do I use swift-format?

The general invocation is swift-format [SUBCOMMAND] [OPTIONS...] [FILES...]. The format subcommand rewrites source and is the default when no subcommand is given, while the lint subcommand reports style violations to standard error without changing files.

### What is swift-format?

It is a formatting technology for Swift source code that provides the formatting behind SourceKit-LSP and the building blocks for code formatting transformations. It can be used as a command line tool or linked into another application as a Swift Package Manager dependency.

### How does swift-format differ from SwiftLint?

swift-format is a formatter that also lints, and the README describes lint as checking for style violations using the same engine that produces formatted output. The swift-format README does not document a comparison with SwiftLint, so the rules each tool covers are not established by the README.

### Does swift-format work in VS Code?

The README states that swift-format provides the formatting technology for SourceKit-LSP, which is the language server editor extensions use. The README does not document a VS Code extension or editor-specific setup steps.

## Sources

- [Issues](https://github.com/swiftlang/swift-format/issues)
- [License: Apache-2.0](https://github.com/swiftlang/swift-format/blob/main/LICENSE)
- [README](https://github.com/swiftlang/swift-format/blob/main/README.md)
- [Releases](https://github.com/swiftlang/swift-format/releases)
- [swiftlang/swift-format on GitHub](https://github.com/swiftlang/swift-format)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/swiftlang-swift-format