SwiftLint

Enforce Swift style and conventions with static analysis. Lint entire projects, autocorrect fixable violations, manage rules, and integrate with Xcode and CI — all from the CLI.

Verify Installation

swiftlint version

If not installed:

brew install swiftlint

Or via Mint:

mint install realm/SwiftLint

Or as a Swift Package Manager plugin (add to

Package.swift

.package(url: "https://github.com/realm/SwiftLint.git", from: "0.57.0")

Then run:

swift package plugin swiftlint

Basic Usage

Lint Current Directory

swiftlint

This recursively lints all

.swift

Lint a Specific Path

swiftlint lint --path Sources/

Lint Specific Files

swiftlint lint --path Sources/App/ViewModel.swift

Lint from Standard Input

cat MyFile.swift | swiftlint lint --use-stdin --quiet

Agent guidance: When a user says "check my code style" or "lint my Swift code," run

swiftlint

from the project root. If they point to a specific file or folder, use

--path

.

Autocorrect

SwiftLint can automatically fix certain violations.

Fix All Autocorrectable Violations

swiftlint --fix

Fix a Specific Path

swiftlint --fix --path Sources/

Fix a Specific File

swiftlint --fix --path Sources/App/ViewModel.swift

Preview What Would Be Fixed (Dry Run)

Lint first to see violations, then fix:

swiftlint lint --path Sources/ && swiftlint --fix --path Sources/

Agent guidance: Always lint before autocorrecting so the user sees what will change. Some violations are not autocorrectable — report those separately after fixing.

Output Formats

Default (Human-Readable)

swiftlint

Output:

Sources/App.swift:12:1: warning: Line Length Violation: ...

JSON

swiftlint lint --reporter json

CSV

swiftlint lint --reporter csv

Checkstyle (XML)

swiftlint lint --reporter checkstyle

GitHub Actions

swiftlint lint --reporter github-actions-logging

Xcode Summary (plist)

swiftlint lint --reporter xcode-summary

SonarQube

swiftlint lint --reporter sonarqube

Markdown

swiftlint lint --reporter markdown

Save to File

swiftlint lint --reporter json > swiftlint-results.json

All Available Reporters

xcode

json

csv

checkstyle

codeclimate

github-actions-logging

sonarqube

markdown

emoji

html

junit

xcode-summary

Agent guidance: Use

--reporter json

when you need to parse results programmatically. Use

--reporter github-actions-logging

on GitHub Actions to get inline annotations on PRs.

Rules

List All Rules

swiftlint rules

Search for a Specific Rule

swiftlint rules | grep "force_cast"

Show Rule Details

swiftlint rules force_cast

Rule Identifiers Quick Reference

Rules fall into categories:

Enabled by Default (Common)

line_length

trailing_whitespace

trailing_newline

opening_brace

closing_brace

colon

let x : Int

let x: Int

comma

force_cast

as!

force_try

try!

force_unwrapping

!

type_body_length

function_body_length

file_length

cyclomatic_complexity

nesting

identifier_name

type_name

unused_import

unused_declaration

vertical_whitespace

todo

mark

void_return

-> Void

-> ()

syntactic_sugar

[Int]

Array<Int>

redundant_optional_initialization

var x: Int? = nil

redundant_string_enum_value

Opt-In (Must Be Explicitly Enabled)

explicit_type_interface

missing_docs

multiline_arguments

multiline_parameters

vertical_parameter_alignment

sorted_imports

file_header

accessibility_label_for_image

accessibility_trait_for_button

strict_fileprivate

private

fileprivate

prohibited_interface_builder

no_magic_numbers

prefer_self_in_static_references

Self

balanced_xctest_lifecycle

test_case_accessibility

Agent guidance: When setting up SwiftLint for a new project, start with defaults and only add opt-in rules the user specifically requests. Don't overwhelm with every possible rule.

Configuration (.swiftlint.yml)

SwiftLint reads

.swiftlint.yml

Generate a Default Config

There's no built-in generator, but here's a minimal config:

# .swiftlint.yml

# Paths to include (default: all Swift files)
included:
  - Sources
  - Tests

# Paths to exclude
excluded:
  - Pods
  - DerivedData
  - .build
  - Packages

# Disable specific rules
disabled_rules:
  - todo
  - trailing_whitespace

# Enable opt-in rules
opt_in_rules:
  - sorted_imports
  - unused_import
  - missing_docs

# Configure specific rules
line_length:
  warning: 120
  error: 200
  ignores_comments: true
  ignores_urls: true

type_body_length:
  warning: 300
  error: 500

file_length:
  warning: 500
  error: 1000

function_body_length:
  warning: 50
  error: 100

identifier_name:
  min_length:
    warning: 2
    error: 1
  max_length:
    warning: 50
    error: 60
  excluded:
    - id
    - x
    - y
    - i
    - j
    - ok

type_name:
  min_length:
    warning: 3
    error: 0
  max_length:
    warning: 50
    error: 60

cyclomatic_complexity:
  warning: 10
  error: 20

nesting:
  type_level:
    warning: 2
  function_level:
    warning: 3

Using a Config from a Custom Path

swiftlint lint --config path/to/.swiftlint.yml

Multiple Configs (Child Config)

# Feature/.swiftlint.yml — inherits parent config and overrides
child_config: ../.swiftlint.yml

disabled_rules:
  - force_cast

Parent Config (Extend from Another)

# .swiftlint.yml
parent_config: shared/.swiftlint-base.yml

Remote Config

parent_config: https://raw.githubusercontent.com/org/repo/main/.swiftlint.yml

Agent guidance: When a project already has

.swiftlint.yml

, always read it before suggesting changes. Modify the existing config rather than creating a new one.

Inline Rule Management

Disable a Rule for a Line

let value = dict["key"] as! String // swiftlint:disable:this force_cast

Disable a Rule for a Block

// swiftlint:disable force_cast
let a = x as! String
let b = y as! Int
// swiftlint:enable force_cast

Disable All Rules for a Block

// swiftlint:disable all
// Legacy code that can't be refactored yet
// swiftlint:disable:enable all

Disable for Next Line Only

// swiftlint:disable:next force_cast
let value = dict["key"] as! String

Disable for Previous Line

let value = dict["key"] as! String
// swiftlint:disable:previous force_cast

Agent guidance: Prefer targeted disables (

disable:this

,

disable:next

) over broad block disables. Never suggest

disable all

unless the user is dealing with generated code or legacy code they explicitly don't want to lint.

Xcode Integration

Build Phase Script

Add a Run Script Phase in Xcode (Build Phases):

if command -v swiftlint >/dev/null 2>&1; then
  swiftlint
else
  echo "warning: SwiftLint not installed, download from https://github.com/realm/SwiftLint"
fi

Build Phase with Autocorrect

if command -v swiftlint >/dev/null 2>&1; then
  swiftlint --fix && swiftlint
fi

Swift Package Plugin (Xcode 15+)

If SwiftLint is added as a package dependency:

swift package plugin swiftlint

Or in Xcode: right-click the project → "SwiftLintBuildToolPlugin".

Agent guidance: For modern projects (Xcode 15+), prefer the SPM plugin over a build phase script — it pins the SwiftLint version to the project and doesn't require a local install.

CI Integration

GitHub Actions

- name: SwiftLint
  run: |
    brew install swiftlint
    swiftlint lint --reporter github-actions-logging --strict

With only changed files:

- name: SwiftLint Changed Files
  run: |
    git diff --name-only --diff-filter=d origin/main...HEAD -- '*.swift' | \
    xargs -I{} swiftlint lint --path {} --reporter github-actions-logging --strict

Bitrise

- script:
    inputs:
    - content: |
        brew install swiftlint
        swiftlint lint --strict

Jenkins (Checkstyle)

swiftlint lint --reporter checkstyle > swiftlint-checkstyle.xml

Then use the Checkstyle plugin to parse

swiftlint-checkstyle.xml

Analyzing Results

Count Violations by Rule

swiftlint lint --reporter json | python3 -c "
import json, sys, collections
data = json.load(sys.stdin)
counts = collections.Counter(v['rule_id'] for v in data)
for rule, count in counts.most_common():
    print(f'{count:>5}  {rule}')
"

Show Only Errors (Not Warnings)

swiftlint lint --strict 2>&1 | grep "error:"

Strict Mode (Warnings Become Errors)

swiftlint lint --strict

This makes SwiftLint return a non-zero exit code for any violation (not just errors).

Quiet Mode (Errors Only in Output)

swiftlint lint --quiet

Suppresses warnings from output, only shows errors.

Enable/Disable Specific Rules via CLI

swiftlint lint --enable-rules sorted_imports,unused_import
swiftlint lint --disable-rules todo,trailing_whitespace

Custom Rules

Define custom regex-based rules in

.swiftlint.yml

custom_rules:
  no_print_statements:
    name: "No Print Statements"
    regex: "\\bprint\\s*\\("
    message: "Use os_log or Logger instead of print()"
    severity: warning
    match_kinds:
      - identifier

  no_hardcoded_strings:
    name: "No Hardcoded Strings in Views"
    regex: "Text\\(\"[^\"]+\"\\)"
    message: "Use LocalizedStringKey or String(localized:) for user-facing text"
    severity: warning
    included: ".*View\\.swift"

  no_force_unwrap_iboutlet:
    name: "No Force Unwrap IBOutlet"
    regex: "@IBOutlet\\s+(weak\\s+)?var\\s+\\w+:\\s+\\w+!"
    message: "Use optional IBOutlets to avoid crashes"
    severity: error

  accessibility_identifier_required:
    name: "Accessibility Identifier"
    regex: "\\.accessibilityIdentifier\\("
    message: "Good — accessibilityIdentifier found"
    severity: warning
    match_kinds:
      - identifier

  prefer_logger_over_print:
    name: "Prefer Logger"
    regex: "\\bNSLog\\s*\\("
    message: "Use Logger (os.Logger) instead of NSLog"
    severity: warning

Match Kinds

identifier

string

comment

keyword

typeidentifier

number

parameter

argument

Agent guidance: Custom rules are powerful but regex-based — they can produce false positives. Always test custom rules on the codebase before suggesting them as permanent additions.

Common Flags Reference

--path <path>

--config <path>

--reporter <name>

--strict

--quiet

--fix

--enable-rules <rules>

--disable-rules <rules>

--use-stdin

--force-exclude

--cache-path <path>

--no-cache

--use-alternative-excluding

--in-process-sourcekit

--compiler-log-path

--progress

Common Workflows

Set Up SwiftLint for a New Project

# 1. Install
brew install swiftlint

# 2. Run initial lint to see baseline
swiftlint lint --path Sources/ --reporter json > baseline.json

# 3. Create config based on results
cat > .swiftlint.yml << 'EOF'
included:
  - Sources
  - Tests
excluded:
  - Pods
  - DerivedData
  - .build
disabled_rules:
  - todo
opt_in_rules:
  - sorted_imports
  - unused_import
line_length:
  warning: 120
  error: 200
  ignores_urls: true
EOF

# 4. Fix autocorrectable issues
swiftlint --fix --path Sources/

# 5. Re-lint to see remaining issues
swiftlint

Fix All Issues Before a PR

# Autocorrect what we can
swiftlint --fix

# Check what remains
swiftlint lint --strict

Lint Only Changed Files (vs. main)

git diff --name-only --diff-filter=d origin/main...HEAD -- '*.swift' | \
  xargs -I{} swiftlint lint --path {} --strict

Compare Violation Counts Between Branches

# Current branch count
CURRENT=$(swiftlint lint --quiet 2>&1 | wc -l | tr -d ' ')

# Main branch count
git stash
git checkout main
MAIN=$(swiftlint lint --quiet 2>&1 | wc -l | tr -d ' ')
git checkout -
git stash pop

echo "main: $MAIN violations, current: $CURRENT violations"

Troubleshooting

Common Errors

No lintable files found

included

Invalid configuration

.swiftlint.yml

SourceKit not found

sudo xcode-select -s /Applications/Xcode.app

Rule not found

swiftlint rules

Slow linting

excluded

--cache-path

Performance Tips

• Always exclude

  Pods/

  ,

  DerivedData/

  ,

  .build/

  , and

  Packages/

  in config
• Use

  --cache-path

  to persist cache across CI runs
• Lint only changed files on CI instead of the entire project
• Use

  --no-cache

  only when debugging unexpected results

Notes

Agent Tips

When a user asks to "clean up" or "fix style" in Swift code, run

swiftlint --fix

first, then

swiftlint lint

to report remaining issues.

Before adding SwiftLint to an existing project, run

swiftlint lint --reporter json

to assess the violation count. If there are hundreds of violations, suggest a phased approach: fix autocorrectable ones first, then tackle the rest by category.

Always check for an existing

.swiftlint.yml

before creating one. Read it to understand the team's style preferences.

For projects targeting accessibility (which should be all of them), suggest enabling

accessibility_label_for_image

and

accessibility_trait_for_button

opt-in rules.

When the user's project uses SwiftUI, suggest a custom rule to catch hardcoded strings in

Text()

views — all user-facing strings should use

String(localized:)

for localization support.

The

--strict

flag is essential for CI — without it, SwiftLint exits 0 even with warnings, which means your CI pipeline won't catch style regressions.