NixOS/nixfmt: Nix Formatting and Repository Workflows

What Nixfmt Standardizes in Nix Projects

Nixfmt is the official formatter for Nix language code. It addresses a specific problem: hand-written Nix expressions can contain inconsistent whitespace, indentation, and layout, making reviews and collaboration harder when formatting choices vary between authors. The repository points to `standard.md` as the definition of the standard Nix format, with artistic formatting incorporated into that standard.

The target audience is developers who edit `.nix` files in NixOS configurations, Home Manager configurations, shell environments, or broader Nix-based repositories. Nixfmt is not a general-purpose formatter for every language, and its editor examples configure it specifically as a Nix formatter. The repository also describes nixfmt as being maintained by the Nix formatting team, which gives the project an official position within the Nix ecosystem.

The main constraint appears before installation details: `nixfmt` can only process one file at a time. A command that formats one file is appropriate for editor save actions and direct invocation, but it does not by itself provide recursive project formatting. The README therefore points developers toward helpers such as `nixfmt-tree`, `treefmt-nix`, `treefmt`, and `pre-commit` when a repository needs broader coverage. This distinction matters for adoption. Teams should decide whether they need a formatter executable, an editor integration, a project-wide command, a commit hook, or all of these.

Nixfmt Installation Paths for Different Environments

The README provides several installation routes because Nix code is commonly managed as configuration rather than installed from a conventional package manager. On NixOS, adding `pkgs.nixfmt` to `environment.systemPackages` makes it available to all users. A per-user installation uses `users.users.<user>.packages`. Home Manager users can add the same package to `home.packages`, while a declarative shell can expose it through `mkShellNoCC`.

For example, the system-wide NixOS configuration is:

{ pkgs, ... }:
{
  environment.systemPackages = [ pkgs.nixfmt ];
}

This makes the formatter available from the configured NixOS environment. For a particular user, the README gives this shape:

{ pkgs, ... }:
{
  users.users.example-user-name.packages = [ pkgs.nixfmt ];
}

Home Manager uses a different option:

{ pkgs, ... }:
{
  home.packages = [ pkgs.nixfmt ];
}

A shell-only installation keeps the executable local to the development environment:

{ pkgs }:
pkgs.mkShellNoCC {
  packages = [ pkgs.nixfmt ];
}

After entering the configured shell, the executable is available to commands and editor integrations run in that environment. The documentation does not provide a standalone installation command for systems outside these Nix-based environments, so it would be unsafe to invent one.

First Use Through an Editor or treefmt

The simplest first use is editor integration. The README shows Neovim configurations for `nixd`, `nil`, and `none-ls`. Each configuration points formatting at the `nixfmt` command, so the command must already be available in the editor's environment. For `nixd`, the documented Lua configuration is:

vim.lsp.config('nixd', = {
    settings = {
        formatting = {
            command = { 'nixfmt' },
        },
    },
})
vim.lsp.enable('nixd')

The `nil` example follows the same command structure, while the `none-ls` example registers `null_ls.builtins.formatting.nixfmt`. Visual Studio Code users can use `vscode-nix-ide` to invoke nixfmt. These integrations are conveniences around the executable, not separate installation methods. If the command is missing, the README explicitly warns that the editor configuration will not work.

For a repository-wide first use, `nixfmt-tree` is the shortest documented path because it provides a `treefmt` instance already configured to use nixfmt. Add it to a shell:

mkShell {
  packages = [ pkgs.nixfmt-tree ];
}

Enter that shell and run `treefmt`. The README says this formats all Nix files in the project. The direct `treefmt` configuration is also documented:

# treefmt.toml
[formatter.nixfmt]
command = "nixfmt"
includes = ["*.nix"]

This configuration still requires nixfmt to be available in the environment. It also shows a boundary in the project model: `nixfmt` handles an individual file, while `treefmt` handles discovery and invocation across the project.

Commit Hooks and Nixfmt Merge Resolution

Nixfmt can be enforced before commits with `pre-commit`, which is useful when formatting consistency should be checked at the boundary between an editor and the repository history. The README gives a repository entry that points at the NixOS nixfmt repository and a hook identifier named `nixfmt`:

repos:
    - repo: https://github.com/NixOS/nixfmt
      rev: <version>
      hooks:
            - id: nixfmt

The `<version>` placeholder is intentional in the README. It should be replaced with a tag for a stable version or a commit hash for an unstable version. The documentation does not prescribe a particular tag in this configuration, so choosing one is a repository policy decision. The hook also requires the `pre-commit` command to be installed and available. The README's setup sequence checks that command, changes into the Git repository, and runs `pre-commit install`.

The repository also documents a `git mergetool` mode:

git config mergetool.nixfmt.cmd 'nixfmt --mergetool "$BASE" "$LOCAL" "$REMOTE" "$MERGED"'
git config mergetool.nixfmt.trustExitCode true

After a failed merge or rebase, the documented command is:

git mergetool -t nixfmt .

A narrower invocation accepts specific files, such as `git mergetool -t nixfmt FILE1 FILE2 FILE3`. The README says some `.nix` files will probably be merged automatically, which is deliberately qualified. Formatting conflicts can still produce a result the developer dislikes. In that case, the documentation provides `git restore --merge .` for the repository or specific file names. The mergetool is a conflict aid, not a guarantee that every merge will resolve cleanly.

Where Nixfmt Is the Wrong Choice

The clearest wrong choice is using nixfmt as a recursive formatter without a helper. The README's installation note says it can only process one file at a time. A script or editor plugin that assumes directory traversal may therefore have the wrong execution model. For project formatting, the documented choices are `nixfmt-tree`, `treefmt-nix`, direct `treefmt`, or a hook configuration. If none of those helpers is part of the workflow, nixfmt alone does not cover the stated project-wide goal.

It is also a poor fit for code outside the Nix language. The documented command is `nixfmt`, while the treefmt example restricts inclusion to `*.nix`:

[formatter.nixfmt]
command = "nixfmt"
includes = ["*.nix"]

The repository does not document JSON, YAML, Markdown, or general source-code formatting behavior for nixfmt. It should not be presented as a replacement for a language-specific formatter outside Nix files.

The merge feature has a narrower purpose than general conflict resolution. The README describes formatting-related conflicts and says that files Git merges successfully before mergetool are ignored. It also uses the qualified phrase that some files will probably be merged automatically. A team that needs deterministic semantic merge support for every conflict should not treat `nixfmt --mergetool` as that tool.

Maintenance, Licensing, and Upgrade Choices

The repository is not archived, and its last push was on 2026-10-14. Recent releases include `v1.5.0` on 2026-09-11, `v1.4.0` on 2026-07-07, and `v1.3.1` on 2026-06-01. These facts indicate recent release activity, but the README does not provide a compatibility policy for formatter output or a migration guide for each version. Teams that use formatting in pre-commit should therefore treat the selected `rev` as part of the repository configuration and review changes when updating it.

The project is licensed under `MPL-2.0`, and the repository includes `LICENSE` and a `LICENSES` directory. The license identifies the project's licensing terms, but this review does not provide legal advice or interpret how a particular organization should comply. The practical adoption question is separate: changing the formatter version can change the expected file layout, so the selected tag or commit should be recorded where the hook or development environment is defined.

The editor examples require nixfmt in the environment, and the project examples use Nix package declarations. This keeps installation tied to Nix configuration, but it also means editor behavior can differ when an editor starts outside the intended shell. Before adopting the tool across a team, verify that the editor, shell, treefmt helper, and pre-commit environment all resolve the same intended formatter version.

Editorial conclusion

Adopt Nixfmt when your team wants the documented standard format for Nix files and can standardize the editor or repository helper around it. Do not adopt it as a standalone directory formatter because the README explicitly says that it processes one file at a time. Verify the installation path, the selected version or commit, the treefmt or pre-commit configuration, and the behavior of `nixfmt --mergetool` in the files and workflows you intend to standardize.

Frequently asked questions

Official sources

1. Issues
2. License: MPL-2.0
3. NixOS/nixfmt on GitHub
4. README
5. Releases