# Fantomas: the opinionated F# formatter that rewrites whole files

> Fantomas is an opinionated source code formatter for F#, distributed as a dotnet global tool and driven by a published style guide. It gives F# teams one fixed layout instead of arguing about whitespace, and the repository is unusually well prepared for coding agents.

**fsprojects/fantomas** — FSharp source code formatter

- Repository: https://github.com/fsprojects/fantomas
- Website: https://fsprojects.github.io/fantomas
- Stars: 835 · Forks: 209
- Language: F#
- License: NOASSERTION
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/fsprojects-fantomas

## The formatting problem Fantomas is built for

Fantomas is described in the README as an opinionated F# source code formatter, and the word opinionated is the whole design brief. It does not offer a menu of style rules or ask you to configure indentation, line breaks and spacing one setting at a time. It applies a single published style, documented as a Style Guide on the project documentation site, and the result is that any file it has touched looks the same as any other file it has touched, regardless of who wrote it or which editor they used.

The audience is F# teams and repositories that have hit the usual friction around that language: formatting rules that differ between Visual Studio, Rider, VS Code and CI, diffs that are entirely whitespace, and reviewers who should be arguing about types rather than about where a line break belongs. Fantomas moves that decision out of the editor and into a command every machine runs the same way.

The distribution is a dotnet global tool, so installation is a one-liner and the tool is available to any machine with the .NET SDK on it. The repository is hosted under the fsprojects organisation, the same home as the wider F# community projects, and the documentation site is published at fsprojects.github.io/fantomas with a docs section for end users and a separate one for contributors.

## Why the AST matters for F# formatting

The repository tags the project with ast and formatter, and that pairing points at the mechanism. Fantomas works from the parsed syntax tree rather than from the raw text of the file. For F# this matters more than it does for most languages, because F# source has layout-dependent syntax: where a line breaks and where an expression is indented changes how the compiler reads it. A formatter that rewrote text line by line would risk changing meaning, and one that operated on a token stream would still have to re-derive the layout rules from the grammar.

Working from the tree lets the formatter decide where line breaks belong from the structure of the code rather than from the shape the author happened to type, and then print the tree back out in the canonical layout. The output is a complete rewrite of the file, not a set of patches to whitespace, which is why the style guide has to be strict rather than configurable.

Two repository entries show how the project keeps that output stable. FormattingConventions.md sits at the root as a written record of the conventions, and there is a separate docs tree under docs/ that the README links to. The build itself is driven by build.fsx, an F# build script, which is the conventional choice in F# repositories and keeps the build logic in the language of the code it builds.

## Installing Fantomas and adding the reporting skill

Installation is a single dotnet tool command, taken from the README:

```bash
dotnet tool install fantomas
```

That places the fantomas executable on your PATH, where you can run it over a file or a project the same way on a laptop and on a build agent. Because it is a dotnet global tool, upgrading is a separate dotnet tool update command rather than a reinstall, and pinning a version for CI is a matter of requesting that version at install time.

The README also documents a newer piece of tooling aimed at contributors and agents. The fantomas-report skill shrinks the file Fantomas failed on down to a minimal sample and opens the pre-filled issue form for you to review, and the README gives its install command:

```bash
npx skills add fsprojects/fantomas --skill fantomas-report -g
```

Taken together, these two commands cover the normal path for a user and the normal path for someone who hit a formatting failure. One caveat worth stating plainly: the README does not document a check-only or no-write mode, does not list the command-line flags, and does not explain how to revert a rewrite. If your CI needs a mode that verifies formatting without touching files, that detail is not in this README and would have to come from the full documentation site.

## EditorConfig, .fantomasignore and the cost of a first run

The repository root carries the two configuration files you would expect from a formatter project: .editorconfig for editor-level behaviour and .fantomasignore for files that Fantomas should leave alone. A .git-blame-ignore-revs file is also present, which is the convention used to mark commits that contain nothing but formatting changes so that git blame skips over them.

That last file is the practical tell. Formatting rewrites produce large diffs, and a large diff on a file nobody edited makes blame useless for the next person who touches it. Teams that adopt Fantomas normally run it once across the repository, commit that as a dedicated formatting commit, and add that commit's hash to .git-blame-ignore-revs so history stays readable afterwards.

The first run is therefore the expensive part, and it is worth planning for. Every file that does not already match the style guide changes, and the resulting diff can be large enough to make review of a concurrent feature branch painful. The cost lands once, at adoption, and then stays near zero because subsequent runs only touch files that have drifted. The trade-off is that Fantomas offers no negotiated format: it is the style guide's layout or it is nothing, so a repository that has grown its own conventions will see those conventions replaced.

## Pointing a coding agent at Fantomas without guessing

The project has gone out of its way to be usable by automated tooling, and this is the most unusual thing in the repository. Two compiled documentation files are published for exactly this purpose: llms.txt, an index of the documentation, and llms-full.txt, the whole thing in one file. The README tells an agent author to hand llms.txt to a coding agent as an index, or llms-full.txt for everything at once, rather than letting the agent guess at flag names.

The repository also carries AGENTS.md, CLAUDE.md and a .claude directory at the root, so agents that look for those files find project instructions before they start editing. The bug reporting path is equally agent-friendly: there is an online tool at fsprojects.github.io/fantomas-tools that opens an issue pre-filled with everything needed to reproduce the failure, and the fantomas-report skill automates the shrinking step that normally produces a tiny test case.

For an F# team using agents to write code, this changes the practical workflow. An agent asked to reformat a file can be pointed at llms-full.txt to learn the real behaviour of the tool rather than inventing invocations, and when the formatter itself fails, the same agent can produce a minimal reproduction. The trade-off is that the documentation set has to be kept in step with the tool, and llms.txt is a generated artefact that can lag behind a release.

## Where Fantomas is the wrong choice

The clearest case against Fantomas is a repository whose current formatting you have already made peace with. A different layout means a one-time diff across every file, and for a project with a long history and regular releases, that is a coordination cost rather than a rounding error. Fantomas is opinionated by construction, so there is no supported mode in which it respects a house style.

The alternative approach is to leave formatting to the editor and let .editorconfig carry the rules, with each developer's F# tooling applying them. The difference in approach is that editor formatting is per machine and per editor version, so two developers can produce two different files without anyone noticing, and CI has no shared definition to check against. Fantomas inverts that: one executable, one layout, the same result everywhere, at the price of the initial rewrite and of dropping the editor's own formatting button.

There is also a licensing question. GitHub cannot classify the licence as one of the standard open source licences, and the terms live in a LICENSE.md file in the repository root. The metadata for the project lists the licence as Other for exactly this reason. That is a reason to read the file rather than an assumption that it is permissive, and it is a genuine differentiator against the MIT-licensed formatters that surround this tool in the wider ecosystem.

## Release cadence and what an upgrade costs

The repository is not archived, and the last push was on 2026-10-22. The release history shows a fast cadence around that date: v8.0.9 and v8.0.10 were both published on 2026-10-14, and v9.0.0-alpha-001 followed on 2026-10-15 under the title October 15 Release. Two patch releases on one day and a major alpha the next is the signature of an actively worked-on project, and it also means upgrades can arrive faster than a team wants to absorb.

For a formatter, the upgrade cost is lower than for a library because the output changes rather than the API. A new major version can restyle files that Fantomas previously formatted, which turns an upgrade into a repository-wide diff again. The.git-blame-ignore-revs convention is useful here as well, since a version bump that reformats the tree deserves its own dedicated commit rather than being folded into unrelated work.

The project is packaged for NuGet and consumed as a global tool, and it also runs on.NET build tooling and CI providers given its.config,.devcontainer,.gitpod.yml and mise.toml files. The development container and gitpod configuration are worth noting for anyone who wants to reproduce a formatting issue: the repository provides a defined environment rather than asking contributors to assemble one.

## Conclusion

Adopt Fantomas when you work in F# and want formatting decisions made once and enforced everywhere, particularly if your editors and CI cannot agree on F# layout. Do not adopt it if you need a formatter that preserves your existing style, and read LICENSE.md before using it commercially because GitHub cannot classify it as a standard open source licence. Check first that the version your team pins matches the one your editor integration expects, since the project shipped v8.0.10 and a v9.0.0 alpha on consecutive days in October 2026.

## FAQ

### How do I install Fantomas for F#?

The README gives a single command, dotnet tool install fantomas, which installs the formatter as a .NET global tool and puts the fantomas executable on your PATH.

### What does the opinionated style of Fantomas mean for an existing repository?

Fantomas applies one published style guide rather than configurable rules, so running it over an existing codebase rewrites any file that does not already match that guide. The README documents a Style Guide page for the details of the layout it produces.

### How do I report a formatting bug in Fantomas?

The README points to an online tool at fsprojects.github.io/fantomas-tools that opens an issue pre-filled with what is needed to reproduce the failure, and the fantomas-report skill shrinks the failing file to a minimal sample and fills the same form.

## Sources

- [fsprojects/fantomas on GitHub](https://github.com/fsprojects/fantomas)
- [Issues](https://github.com/fsprojects/fantomas/issues)
- [Project website](https://fsprojects.github.io/fantomas)
- [README](https://github.com/fsprojects/fantomas/blob/main/README.md)
- [Releases](https://github.com/fsprojects/fantomas/releases)

---

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