scalafmt: a configurable formatter for Scala repositories

Why scalafmt matters in a Scala repository

scalafmt addresses source formatting, one of the recurring consistency problems in Scala codebases. Contributors may use different editors and operating systems, while a shared repository still needs to produce predictable formatting and reviewable diffs. The project is aimed at Scala developers and teams that want formatting policy to come from the repository rather than from each contributor's editor settings.

The repository also serves contributors who modify formatter behavior. It includes separate modules for the core implementation, configuration, command-line use, interfaces, macros, dynamic behavior, documentation, tests, and benchmarks. This layout suggests an architecture designed both for end-user integration and for development inside the formatter itself.

Its scope remains narrower than that of a compiler, linter, dependency manager, or semantic refactoring engine. Scalafmt changes the presentation of Scala source according to formatting rules. It should not be selected to diagnose code defects, upgrade libraries, change APIs, or migrate Scala syntax. Those jobs require different tools. The distinction is important because a formatter can reduce formatting churn without solving broader code-quality concerns.

The root `.scalafmt.conf` gives the repository itself a formatter configuration. Teams adopting the project can follow that model by reviewing configuration changes in source control and applying a documented editor, CLI, or build integration. The README points to separate user documentation for installation and operating instructions.

How the scalafmt module structure separates concerns

Based on the repository layout, `scalafmt-core` contains central formatter code, while `scalafmt-config` is assigned a separate module for configuration concerns. `scalafmt-cli` provides a command-line-oriented component, and `scalafmt-interfaces` gives other callers a separate integration surface. Additional modules include `scalafmt-dynamic`, `scalafmt-dynamic-core`, `scalafmt-macros`, and `scalafmt-sysops`.

This separation supports several operating contexts. A contributor working in an editor needs a low-friction path that can format selected files or a buffer. A build integration needs a programmatic entry point and stable configuration handling. A command-line or container workflow needs packaging that can run outside an interactive editor. The named modules indicate that these responsibilities are not all confined to the CLI.

The repository also distinguishes ordinary correctness checks from formatting-specific checks. The README lists the complete unit suite and a narrower command for `FormatTests`. It separately documents commands for build tooling, benchmarks, and large input sets. A new formatting test is associated with `scalafmt-tests/shared/src/test/resources/readme.md`, indicating that expected formatting behavior has a dedicated test structure.

The README does not explain the parser, rewrite sequence, configuration precedence, or file-discovery algorithm. It also does not document how `scalafmt-dynamic` selects a formatter version. Those details should not be inferred from module names. A custom integration should use the documented interface for its chosen entry point and confirm configuration behavior in the user documentation.

Building scalafmt and running the first documented checks

The README does not contain a complete end-user installation tutorial. It directs users to the linked user documentation for installation, so it would be misleading to substitute a guessed package-manager command or CLI flag. The available commands are contributor-oriented and can verify that the repository builds and that its tests run.

The README lists two compilation forms. The first builds through sbt, while the second selects the core project specifically:

sbt compile

sbt core/compile

After compilation, the documented command for all unit tests is:

sbt test

For a narrower check of formatter behavior, the README identifies this selection:

sbt testOnly *FormatTests

These commands are useful for contributors evaluating a checkout, but they do not prove compatibility with an external Scala repository. A first real use requires loading the project in the user's chosen editor or running the installed executable, then checking a small set of Scala files. The README does not provide that editor command or a complete invocation against a sample directory.

The repository root contains `.scalafmt.conf`, which offers a concrete configuration reference. Before applying scalafmt throughout another repository, a team should review that file and compare its resulting changes with existing code. A small diff is easier to evaluate than an immediate rewrite of every Scala file.

Building and running scalafmt from the repository Dockerfile

The root `Dockerfile` provides a Linux packaging mechanism. It accepts `VERSION` and `TARGETARCH` build arguments, selects an architecture-specific release archive, installs temporary download tools, and places the formatter executable at `/bin/scalafmt`. Supported branches are explicit: `amd64` selects `x86_64`, and `arm64` selects `aarch64`. Any other architecture causes the build to exit with an unsupported-architecture message.

The image is based on Alpine. After extracting the archive, it removes temporary build dependencies, adds `gcompat` and `libstdc++`, and changes the executable permissions. Its final entry point is:

ENTRYPOINT ["/bin/scalafmt"]

The repository does not show a complete `docker build` tutorial, an official image name, a supported image tag, or a workspace-mount example. It would therefore be unsafe to invent those details. The file confirms how a release archive can become a containerized command, but readers still need a valid `VERSION` value and the GitHub release asset naming expected by the file.

This packaging is specifically useful for teams that already execute formatting in Linux containers. It supports two architecture mappings in the Dockerfile, not every processor or operating system. Native Windows users also have a separate `scalafmt.ps1` entry at the repository root, although the README excerpt does not explain its usage.

Formatter tests, benchmarks, and large repositories

scalafmt separates normal tests from expensive performance work. The README documents `sbt test` for all unit tests and `sbt testOnly *FormatTests` for formatting tests. It also identifies a `scalafmt-benchmarks` module and provides a script for running JMH benchmarks:

./bin/run-benchmarks.sh

A separate command is documented for running the formatter on millions of lines of code:

tests/test:runMain  org.scalafmt.ScalafmtProps

The README labels this operation as slow and says it requires substantial CPU and memory. That is an operational constraint for teams considering repository-wide formatting or CI scheduling. No benchmark values are included, so the project cannot be assigned a specific throughput or compared numerically with another formatter from the README.

Performance analysis has a documented output path. After each `FormatTests` run, the README states that a flamegraph report is generated at `target/index.html`. For local inspection, it gives this BrowserSync command:

browser-sync start --server --files "target/*.html"

BrowserSync is a separate local tool used to serve the report. It is not part of formatting production files. The README also warns that the millions-of-lines command is slow and memory intensive, so contributors should use the narrower format tests and benchmark entry points while investigating behavior.

Documentation tooling kept outside Scala formatting

The repository's `package.json` defines two Prettier scripts, but their target is the `docs` directory. These commands format or check documentation files and do not replace scalafmt for `.scala` sources. Keeping the tools separate prevents an editor or automation script from applying the wrong formatter to the wrong file type.

The documented documentation commands are:

{
  "name": "Scalafmt",
  "scripts": {
    "format": "prettier --write docs",
    "format-check": "prettier --check docs"
  }
}

The project also instructs documentation contributors to follow `docs/contributing-website.md` for a local website build. That separates Scala source formatting from formatting the documentation sources with Prettier. Teams adopting scalafmt should avoid copying the root `package.json` scripts as a Scala formatting policy.

The build and documentation tooling reflect a multi-part project. `build.sbt` organizes Scala modules, while `package.json` manages JavaScript-based documentation formatting. The root files do not show a promise that one command handles every file in the repository. Contributors need to identify whether the target is Scala source, benchmark code, tests, documentation, or generated site content.

Release cadence, licensing, and formatter alternatives

The repository is not archived, and its last push was on 2026-10-15. Recent releases include `v3.11.5` on 2026-07-27, `v3.11.4` on 2026-07-17, and `v3.11.3` on 2026-07-11. This history supports expecting recent project changes, but release dates do not establish compatibility with every Scala release or editor. Upgrade testing remains necessary because a new formatter release can change formatting output and produce repository-wide diffs.

The repository identifies the project as licensed under Apache-2.0 and includes `LICENCE.md`. Organizations using scalafmt in internal build systems or redistributed container images should review that file and any relevant third-party notices under their own compliance process. This paragraph is not legal advice.

A real alternative is an editor's built-in Scala formatter. Its approach differs. An editor formatter runs inside one editing environment and usually depends on that editor's settings, while scalafmt maintains a repository configuration and separate core, CLI, interface, dynamic, and packaging components. The editor option may serve an individual contributor well, but it does not by itself provide the repository-wide integration points shown by scalafmt.

The README does not name a competing formatter or document an output-quality comparison. The choice should therefore be based on confirmed integration support and a controlled test against the team's Scala files, not on an unsupported claim that one formatter always produces better results.

Editorial conclusion

Scala teams that want one reviewable formatting policy across editors, builds, and automation should evaluate scalafmt. Projects needing semantic refactoring or more detailed platform guidance should not treat it as a replacement for those tools. Before adoption, check the linked user documentation, select the supported editor or build integration, and format a representative set of existing Scala files to inspect the resulting diff.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. scalameta/scalafmt on GitHub