Troubleshoot the most common SwiftFormat installation problem, the command not found error, and get the CLI running reliably on your Mac.
You installed SwiftFormat, you type a command in Terminal, and the shell answers with `swiftformat: command not found`. It is one of the most common first-time problems, and it is almost always about where the binary lives rather than a broken tool.
The error means your shell searched the directories on its PATH and did not find an executable named swiftformat. The tool may be installed perfectly; the shell simply cannot see it.
That distinction is the key to fixing it quickly. You are not chasing a corrupt download or a bug in SwiftFormat; you are reconciling where the binary lives with where your shell looks.
The good news is that this is a well-understood class of problem with a short list of causes.
Working through them methodically will get you running. None of the steps below are risky, and each one narrows down where the real problem is, so resist the urge to reinstall repeatedly and hope it sticks.
Start by separating two questions: is SwiftFormat installed, and can your shell find it. If you installed with Homebrew, ask Homebrew directly whether it thinks the package is present.
Running `brew list swiftformat` or checking `brew info swiftformat` tells you whether Homebrew installed the tool. If it reports the package, installation succeeded and your problem is almost certainly PATH-related.
This single check saves a lot of wasted effort, because it immediately tells you which half of the problem you are in. Knowing the binary exists on disk lets you focus entirely on the PATH.
If Homebrew does not know about it, the installation itself did not complete. In that case, reinstall with `brew install swiftformat` and watch the output for any errors rather than assuming it worked.
Installation failures often scroll past in a wall of text, so read the tail of the output carefully for permission problems or interrupted downloads before moving on.
The most frequent cause of command not found is that the directory containing the binary is not on your PATH. Homebrew installs binaries into a specific location that differs between Apple Silicon and Intel Macs, and a freshly configured shell sometimes does not include it.
On Apple Silicon Macs, Homebrew typically installs under /opt/homebrew, while on Intel Macs it uses /usr/local. If your shell profile was set up for one and you are on the other, the binary directory can be missing from PATH.
Check what your shell sees by running `echo $PATH` and confirm the relevant Homebrew binary directory is listed. Homebrew's own setup instructions, printed after installation, tell you exactly which line to add to your shell profile.
After updating your shell profile, open a new Terminal window or reload the profile so the change takes effect. Then try `swiftformat --version` again.
If you are unsure which directory Homebrew uses on your machine, running `brew --prefix` points you at the base location, and the binary lives in its bin subdirectory.
A surprisingly common cause is simply that you are in a shell session that started before the installation finished. Environment changes do not always apply retroactively to an open terminal.
Close the terminal entirely and open a fresh one, then retry the command. This forces a new session that reads your current configuration.
Opening a new tab is not always enough, depending on how your terminal is set up, so fully quitting and relaunching the terminal application is the most reliable way to guarantee a clean session.
If the command works in the new session but not the old one, that was the whole problem. It is a harmless quirk of how shells load their environment, not a sign of anything broken.
Before digging into deeper PATH surgery, always try this simple restart. It resolves the issue often enough that it is worth ruling out first, and it costs almost nothing to attempt.
Modern macOS defaults to zsh, but some developers use bash or another shell. Each shell reads a different startup file, so a PATH line added to the wrong file has no effect.
Confirm your shell with `echo $SHELL`, then make sure your PATH changes go into the startup file that shell actually reads. Editing a bash profile will not help a zsh session.
For zsh the relevant file is usually a profile in your home directory read at shell startup, while bash reads its own separate files. Putting the line in the wrong one produces the frustrating case where everything looks correct but nothing changes.
This mismatch is easy to overlook and produces exactly the confusing behavior where everything looks configured but the command still is not found.
Aligning the change with your real shell resolves it. If you recently switched shells, double-check that your PATH additions moved to the new shell's startup file as well.
Once you believe the problem is solved, verify decisively. Run `which swiftformat` to see the full path the shell resolves for the command, and `swiftformat --version` to confirm it executes.
A printed path and version number together mean the tool is installed and reachable. From here, normal usage should work.
Using both commands rather than one is deliberate. `which` proves the shell can locate the binary, and `--version` proves the binary actually runs, which are two separate things worth confirming.
If `which` finds nothing, the binary is still not on your PATH, and you should revisit the PATH steps.
If `which` finds it but it will not run, you may have a permissions or architecture issue worth investigating separately. An Intel binary on an Apple Silicon machine without the right support can be found yet fail to execute, so keep that possibility in mind.
A trickier variant is when swiftformat works in your interactive terminal but fails as command not found inside a Git hook or an Xcode build phase. These non-interactive environments often use a minimal PATH that excludes your normal shell customizations.
The reliable fix is to reference the tool in a way that does not depend on your interactive PATH, for example by using its full installed path or by ensuring the script sets up the environment it needs.
Hardcoding the absolute path to the binary, or detecting it at the top of the script, sidesteps the whole problem because the script no longer relies on inheriting your personal shell configuration.
This is a common gotcha specifically because the tool clearly is installed, yet the automated context cannot find it.
Treat the hook or build script as its own environment rather than assuming it inherits your terminal's. Discovering the full installed path with `which swiftformat` in your terminal gives you a value you can reference directly in the script.
Getting the command to run is purely about your local environment and installation, not about SwiftFormat itself being flawed. Once `swiftformat --version` works, the tool will format your code as designed.
None of these steps touch the tool's actual behaviour; they only change whether your shell can find and launch it. That is why the fixes are all about PATH, shells, and environments rather than SwiftFormat's rules.
Keep the broader picture in mind while troubleshooting. SwiftFormat is a source-code formatter, so none of these fixes touch building, signing, or App Store submission, which depend on Xcode and the Apple Developer Program.
If you remain stuck after these steps, the project's official GitHub repository and its issues are the authoritative place to check for environment-specific guidance.
When searching or reporting there, include your macOS version, your chip architecture, your shell, and how you installed the tool, since those details usually determine the fix.
Your shell cannot find the swiftformat binary on its PATH. The tool may be installed correctly, but the directory containing it is not in your PATH, so the shell reports it as missing.
If you used Homebrew, run brew list swiftformat or brew info swiftformat. If Homebrew reports the package, it is installed and the issue is PATH-related; if not, reinstall and watch for errors.
Non-interactive environments like hooks and build phases often use a minimal PATH that excludes your shell customizations. Reference the tool by its full installed path or set up the needed environment in the script.
Make sure you edited the startup file for your actual shell (check echo $SHELL) and open a fresh terminal so the change loads. A change in the wrong profile or an old session will not take effect.
Run which swiftformat to see the resolved path and swiftformat --version to confirm it runs. A path and version number together mean it is installed and reachable.