nixfmt

# Nixfmt

Nixfmt is the official formatter for Nix language code.
The standard Nix format incorporates artistic formatting and is defined in [standard.md](./standard.md).
Nixfmt is maintained by the [Nix formatting team](https://nixos.org/community/teams/formatting/).
This document is the user documentation, see [CONTRIBUTING.md](./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-a-project).

### In the environment

#### NixOS

To install `nixfmt` on NixOS for all users, add it to the [`environment.systemPackages`](https://search.nixos.org/options?show=environment.systemPackages) configuration option:

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

To install it on NixOS for a particular user, add it to the [`users.users.<user>.packages`](https://search.nixos.org/options?show=users.users.%3Cname%3E.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`](https://nix-community.github.io/home-manager/options.xhtml#opt-home.packages) configuration option:

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

#### Declarative shell environment

To make `nixfmt` available in a shell environment invoked with [`nix-shell`](https://nix.dev/manual/nix/2.28/command-ref/nix-shell), add it to the `packages` argument of `mkShell`:

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

### In an editor

#### neovim + nixd

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

> [!NOTE]
> This only works when `nixfmt` is available [in the environment](#in-the-environment).

#### neovim + nil

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

> [!NOTE]
> This only works when `nixfmt` is available [in the environment](#in-the-environment).

#### neovim + none-ls

```lua
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](#in-the-environment).

#### Visual Studio Code (VSC)

[vscode-nix-ide](https://github.com/nix-community/vscode-nix-ide) can invoke `nixfmt`.

> [!NOTE]
> This only works when `nixfmt` is available [in the environment](#in-the-environment).

### In a project

#### `nixfmt-tree`

[`nixfmt-tree`](https://search.nixos.org/packages?channel=unstable&show=nixfmt-tree) provides an instance of `treefmt`, pre-configured to use nixfmt.

Simply add it to your shell:

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

Then run `treefmt` from