NixOS/nixfmt

Nixfmt

Nixfmt is the official formatter for Nix language code. The standard Nix format incorporates artistic formatting and is defined in standard.md. Nixfmt is maintained by the Nix formatting team. This document is the user documentation, see CONTRIBUTING.md for contributor documentation.

Installation

[!NOTE] nixfmt can only process one file at a time. Consider using a configuration helper for formatting a project.

In the environment

NixOS

To install nixfmt on NixOS for all users, add it to the environment.systemPackages configuration option:

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

To install it on NixOS for a particular user, add it to the users.users.<user>.packages configuration option:

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

Home Manager

To install nixfmt in Home Manager, add it to the home.packages configuration option:

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

Declarative shell environment

To make nixfmt available in a shell environment invoked with nix-shell, add it to the packages argument of mkShell:

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

In an editor

neovim + nixd

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

[!NOTE] This only works when nixfmt is available in the environment.

neovim + nil

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

[!NOTE] This only works when nixfmt is available in the environment.

neovim + none-ls

local null_ls = require("null-ls")
null_ls.setup({
    sources = {
        null_ls.builtins.formatting.nixfmt,
    },
})

[!NOTE] This only works when nixfmt is available in the environment.

Visual Studio Code (VSC)

vscode-nix-ide can invoke nixfmt.

[!NOTE] This only works when nixfmt is available in the environment.

In a project

nixfmt-tree

nixfmt-tree provides an instance of treefmt, pre-configured to use nixfmt.

Simply add it to your shell:

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

Then run treefmt from within your shell to format all nix files in your project.

treefmt-nix

treefmt-nix automatically configures the correct packages and formatters for treefmt using the Nix language, and has native support for nixfmt:

{ pkgs, treefmt-nix }:
treefmt-nix.mkWrapper pkgs {
  programs.nixfmt.enable = true;
};

treefmt

treefmt can also be used directly:

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

[!NOTE] This only works when nixfmt is available in the environment.

git-hooks.nix

git-hooks.nix can automatically configure Git hooks like pre-commit using the Nix language, and has native support for nixfmt:

{ pkgs, git-hooks }:
{
  pre-commit-check = git-hooks.run {
    hooks = {
      nixfmt.enable = true;
    };
  };
  shell = pkgs.mkShellNoCC {
    packages = [ pre-commit-check.enabledPackages ];
    shellHook = ''
      ${pre-commit-check.shellHook}
    '';
  };
}

pre-commit

pre-commit can also be used directly:

1. Make sure that you have the pre-commit command:

   $ pre-commit --version
   pre-commit 3.7.1
   

2. Make sure that you’re in your Git repo:

   $ cd <path-to-git-repo>
   

3. Make sure that the pre-commit tool is installed as a Git pre-commit hook:

   $ pre-commit install
   pre-commit installed at .git/hooks/pre-commit
   

4. If you don’t already have one, then create a .pre-commit-config.yaml file.

5. Add an entry for the nixfmt hook to your .pre-commit-config.yaml file:

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

   If you want to use a stable version of nixfmt, then replace <version> with a tag from this repo. If you want to use an unstable version of nixfmt, then replace <version> with a commit hash from this repo.

6. Try to commit a badly formatted Nix file in order to make sure that everything works.

git mergetool

nixfmt provides a mode usable by git mergetool via --mergetool that allows resolving formatting-related conflicts automatically in many cases.

It can be installed by any of these methods:

• For only for the current repo, run:

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

• For all repos with a mutable config file, run

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

• For all repos with a NixOS-provided config file, add this to your configuration.nix:

  programs.git.config = {
    mergetool.nixfmt = {
      cmd = "nixfmt --mergetool \"$BASE\" \"$LOCAL\" \"$REMOTE\" \"$MERGED\"";
      trustExitCode = true;
    };
  };
  

• For all repos with a home-manager-provided config file, add this to your home.nix:

  programs.git.extraConfig = {
    mergetool.nixfmt = {
      cmd = "nixfmt --mergetool \"$BASE\" \"$LOCAL\" \"$REMOTE\" \"$MERGED\"";
      trustExitCode = true;
    };
  };
  

Then, when git merge or git rebase fails, run

git mergetool -t nixfmt .
# or, only for some specific files
git mergetool -t nixfmt FILE1 FILE2 FILE3

and some .nix files will probably get merged automagically.

Note that files that git merges successfully even before git mergetool will be ignored by `git mergetool`.

If you don't like the result, run

git restore --merge .
# or, only for some specific files
git restore --merge FILE1 FILE2 FILE3

to return back to the unmerged state.

nix fmt (experimental)

nix fmt (part of the flakes experimental feature) can be configured to use nixfmt by setting the formatter flake output to nixfmt-tree (assuming a nixpkgs flake input exists):

# flake.nix
{
  outputs =
    { nixpkgs, self }:
    {
      formatter.x86_64-linux = nixpkgs.legacyPackages.x86_64-linux.nixfmt-tree;
    };
}

Usage

• nixfmt < input.nix – reads Nix code from stdin, formats it, and outputs to stdout
• nixfmt file.nix – format the file in place

Disabling Formatting

If you're using treefmt, you can include and exclude files via treefmt's configuration.

Within formatted nix files, you can use Nixfmt "directives" to enable and disable formatting from that line onwards.

For example:

{
  terrible-example-you-should-not-copy = {
    /*nixfmt:disable*/
    foo    =    1;
    bar    =    2;
    /*nixfmt:enable*/
    baz = 3;
  };
}

Acknowledgements

nixfmt was originally developed by Serokell and later donated to become an official Nix project with the acceptance of RFC 166.