Learn how to create and structure a .swiftlint.yml configuration file to enable, disable, and tune SwiftLint rules so the linter matches your team's Swift style.
Out of the box, SwiftLint applies a sensible set of default rules. But every team has its own conventions, and few teams agree with every default.
The configuration file, `.swiftlint.yml`, is where you make SwiftLint yours. You decide which rules run, how strict they are, and which files they ignore.
Getting this file right is the difference between a linter people trust and one they mute out of frustration. A well-tuned configuration surfaces genuine issues without drowning developers in noise.
This guide walks through creating the file, the most useful keys, and a sane strategy for rolling it out.
SwiftLint looks for a file named `.swiftlint.yml` in the directory where it runs, which is normally your project root. Create an empty one there.
From Terminal at your project root you can simply create the file with your editor of choice, or add it through Xcode by choosing New File and naming it exactly `.swiftlint.yml`. The leading dot matters.
Because the name starts with a dot, macOS Finder hides it by default. Press Command-Shift-Period in Finder to reveal hidden files if you need to see it.
Commit this file to version control. Its whole purpose is to give every developer and your CI system identical linting behavior.
The configuration file is YAML, so it is just keys and lists. A handful of top-level keys cover most needs.
`disabled_rules` turns off default rules you do not want. `opt_in_rules` turns on stricter rules that are off by default. `only_rules` is the opposite extreme — it runs exactly the listed rules and nothing else.
`excluded` lists paths SwiftLint should skip entirely, such as generated code, third-party dependencies, or your Pods directory. `included` can narrow the search to specific paths.
Many individual rules also accept their own parameters, letting you set warning and error thresholds. This is how you tell a length rule where a warning becomes an error, for example.
Start by silencing rules that genuinely do not fit your team. Under `disabled_rules`, list rule identifiers, one per line as a YAML list.
For example, if your team dislikes a particular default, add its identifier there and it stops firing. Keep this list short and intentional — every disabled rule is a small concession.
Next, browse the rule directory for opt-in rules that match your standards, and add their identifiers under `opt_in_rules`. Opt-in rules tend to encode stricter or more opinionated conventions that many teams actively want.
A good habit is to leave a brief YAML comment next to non-obvious entries explaining why a rule is disabled or enabled. Six months later, that context is gold.
Many rules are configurable rather than simply on or off. Length-based rules — for lines, functions, types, and files — commonly accept both a warning threshold and an error threshold.
You configure these by nesting values under the rule's name. For instance, you can raise a line-length warning threshold if your team writes wider lines, and set a separate, higher error threshold for lines that are truly unacceptable.
Severity is the other lever. Some rules let you declare whether a violation is a warning or an error, which controls whether it merely annotates or can fail a strict build.
Check each rule's documentation in the official rule directory for the exact parameters it supports, since they vary. When in doubt, run the linter after each change to confirm the effect.
You almost never want to lint code you did not write or that is machine-generated. This is what the `excluded` key is for.
List directories such as your dependency manager's folder, generated API clients, and any build output. Paths are relative to the configuration file's location.
Excluding these directories does two things: it removes noise from code you cannot change, and it speeds up linting by giving SwiftLint less to scan.
Be careful not to over-exclude your own source. The goal is to skip third-party and generated code, not to hide real violations in files you actually maintain.
Beyond the built-in library, SwiftLint supports custom rules defined with regular expressions. This is powerful for enforcing team-specific conventions the built-in rules do not cover.
Under a `custom_rules` key, you define a named rule with a regex pattern to match, a message to display, and a severity. For example, teams sometimes forbid a particular deprecated API name or a specific logging call.
Custom rules are text-pattern based, so they are best for straightforward lexical conventions rather than deep semantic checks. Keep patterns tight to avoid false positives.
Test each custom rule against real code before committing it. A noisy or over-broad custom rule erodes trust in the whole configuration quickly.
On a fresh project, you can turn on a strict configuration immediately. On an existing codebase, resist that urge.
Enabling everything at once on legacy code can produce a flood of violations that overwhelms the team and gets the linter ignored. Instead, start close to defaults and tighten over time.
A proven strategy is to add stricter rules one or a few at a time, fix the resulting violations, then commit. Each increment leaves the codebase cleaner without a demoralizing mega-cleanup.
Whenever you change the configuration, run SwiftLint locally and, ideally, in CI so everyone sees the same results. Keep the config in version control so it evolves as a reviewed, shared artifact.
A pragmatic first configuration disables a couple of defaults your team dislikes, opts into a handful of stricter rules you agree with, excludes generated and dependency directories, and tunes one or two length thresholds.
Resist the temptation to copy a giant configuration from the internet wholesale. Borrowing ideas is fine, but every disabled or enabled rule should be a deliberate choice your team understands.
Remember the boundaries of the tool. Configuration controls style enforcement only; it does not affect how your app compiles, signs, or ships, which remain Xcode's job and require an Apple Developer Program membership for release.
With a thoughtful `.swiftlint.yml` committed, your linter now reflects your team's actual standards — consistent, low-noise, and trusted.
Place it at your project root, the directory where SwiftLint runs. It applies to the Swift files found from there, minus anything you exclude. Commit it so everyone shares the same configuration.
disabled_rules turns off defaults you do not want. opt_in_rules turns on stricter rules that are off by default. only_rules runs exactly the listed rules and nothing else, ignoring all defaults.
Nest warning and error threshold values under the rule's name in the YAML file. Check the official rule directory for the exact parameters each rule supports, since they differ per rule.
Yes, using the custom_rules key with a regular expression, a message, and a severity. These are text-pattern based, so they work best for simple lexical conventions rather than deep semantic checks.