{"id":15171120,"url":"https://github.com/nixos/nixfmt","last_synced_at":"2025-12-11T23:28:58.830Z","repository":{"id":35088385,"uuid":"143292270","full_name":"NixOS/nixfmt","owner":"NixOS","description":"The official (but not yet stable) formatter for Nix code","archived":false,"fork":false,"pushed_at":"2025-05-09T21:03:09.000Z","size":1061,"stargazers_count":1132,"open_issues_count":29,"forks_count":54,"subscribers_count":34,"default_branch":"master","last_synced_at":"2025-05-09T22:19:22.804Z","etag":null,"topics":["formatter","haskell","nix"],"latest_commit_sha":null,"homepage":"","language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NixOS.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"open_collective":"nixos"}},"created_at":"2018-08-02T12:33:51.000Z","updated_at":"2025-05-09T21:03:13.000Z","dependencies_parsed_at":"2023-10-11T17:49:05.327Z","dependency_job_id":"9cbecc06-6498-4eb8-b12c-68c449a4b6c6","html_url":"https://github.com/NixOS/nixfmt","commit_stats":{"total_commits":413,"total_committers":27,"mean_commits":"15.296296296296296","dds":0.6997578692493946,"last_synced_commit":"30907b667b682564b7e54061bc4e3446305bc168"},"previous_names":["nixos/nixfmt","serokell/nixfmt"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NixOS%2Fnixfmt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NixOS%2Fnixfmt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NixOS%2Fnixfmt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NixOS%2Fnixfmt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NixOS","download_url":"https://codeload.github.com/NixOS/nixfmt/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254198514,"owners_count":22030965,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["formatter","haskell","nix"],"created_at":"2024-09-27T09:00:30.781Z","updated_at":"2025-12-11T23:28:58.824Z","avatar_url":"https://github.com/NixOS.png","language":"Haskell","funding_links":["https://opencollective.com/nixos"],"categories":[],"sub_categories":[],"readme":"![Build Status](https://github.com/NixOS/nixfmt/actions/workflows/main.yml/badge.svg?branch=master)\n\n# Nixfmt\n\nNixfmt is the official formatter for Nix language code.\nIt is maintained by the [Nix formatting team](https://nixos.org/community/teams/formatting/).\nThis document is the user documentation, see [CONTRIBUTING.md](./CONTRIBUTING.md) for contributor documentation.\n\n## Installation\n\n\u003e [!NOTE]\n\u003e `nixfmt` can only process one file at a time.\n\u003e Consider using a configuration helper for [formatting a project](#in-a-project).\n\n### In the environment\n\n#### NixOS\n\nTo install `nixfmt` on NixOS for all users, add it to the [`environment.systemPackages`](https://search.nixos.org/options?show=environment.systemPackages) configuration option:\n\n```nix\n{ pkgs, ... }:\n{\n  environment.systemPackages = [ pkgs.nixfmt-rfc-style ];\n}\n```\n\nTo install it on NixOS for a particular user, add it to the [`users.users.\u003cuser\u003e.packages`](https://search.nixos.org/options?show=users.users.%3Cname%3E.packages) configuration option:\n\n```\n{ pkgs, ... }:\n{\n  users.users.example-user-name.packages = [ pkgs.nixfmt-rfc-style ];\n}\n```\n\n#### Home Manager\n\nTo 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:\n\n```nix\n{ pkgs, ... }:\n{\n  home.packages = [ pkgs.nixfmt-rfc-style ];\n}\n```\n\n#### Declarative shell environment\n\nTo 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`:\n\n```nix\n{ pkgs }:\npkgs.mkShellNoCC {\n  packages = [ pkgs.nixfmt-rfc-style ];\n}\n```\n\n### In an editor\n\n#### neovim + nixd\n\n```lua\nlocal nvim_lsp = require(\"lspconfig\")\nnvim_lsp.nixd.setup({\n   settings = {\n      nixd = {\n         formatting = {\n            command = { \"nixfmt\" },\n         },\n      },\n   },\n})\n```\n\n\u003e [!NOTE]\n\u003e This only works when `nixfmt` is available [in the environment](#in-the-environment).\n\n#### neovim + nil\n\n```lua\nlocal nvim_lsp = require(\"lspconfig\")\nnvim_lsp.nil_ls.setup({\n   settings = {\n      ['nil'] = {\n         formatting = {\n            command = { \"nixfmt\" },\n         },\n      },\n   },\n})\n```\n\n\u003e [!NOTE]\n\u003e This only works when `nixfmt` is available [in the environment](#in-the-environment).\n\n#### neovim + none-ls\n\n```lua\nlocal null_ls = require(\"null-ls\")\nnull_ls.setup({\n    sources = {\n        null_ls.builtins.formatting.nixfmt,\n    },\n})\n```\n\n\u003e [!NOTE]\n\u003e This only works when `nixfmt` is available [in the environment](#in-the-environment).\n\n#### Visual Studio Code (VSC)\n\n[vscode-nix-ide](https://github.com/nix-community/vscode-nix-ide) can invoke `nixfmt`.\n\n\u003e [!NOTE]\n\u003e This only works when `nixfmt` is available [in the environment](#in-the-environment).\n\n### In a project\n\n#### `nixfmt-tree`\n\n[`nixfmt-tree`](https://search.nixos.org/packages?channel=unstable\u0026show=nixfmt-tree) provides an instance of `treefmt`, pre-configured to use nixfmt.\n\nSimply add it to your shell:\n\n```nix\nmkShell {\n  packages = [ pkgs.nixfmt-tree ];\n}\n```\n\nThen run `treefmt` from within your shell to format all nix files in your project.\n\n#### `treefmt-nix`\n\n[`treefmt-nix`](https://github.com/numtide/treefmt-nix) automatically configures the correct packages and formatters for [`treefmt`](https://github.com/numtide/treefmt) using the Nix language, and has native support for `nixfmt`:\n\n```nix\n{ pkgs, treefmt-nix }:\ntreefmt-nix.mkWrapper pkgs {\n  programs.nixfmt.enable = true;\n};\n```\n\n#### `treefmt`\n\n[`treefmt`](https://github.com/numtide/treefmt) can also be used directly:\n\n```toml\n# treefmt.toml\n[formatter.nixfmt-rfc-style]\ncommand = \"nixfmt\"\nincludes = [\"*.nix\"]\n```\n\n\u003e [!NOTE]\n\u003e This only works when `nixfmt` is available [in the environment](#in-the-environment).\n\n#### `git-hooks.nix`\n\n[`git-hooks.nix`](https://github.com/cachix/git-hooks.nix) can automatically configure Git hooks like [`pre-commit`](https://pre-commit.com/) using the Nix language, and has native support for `nixfmt`:\n\n```nix\n{ pkgs, git-hooks }:\n{\n  pre-commit-check = git-hooks.run {\n    hooks = {\n      nixfmt-rfc-style.enable = true;\n    };\n  };\n  shell = pkgs.mkShellNoCC {\n    packages = [ pre-commit-check.enabledPackages ];\n    shellHook = ''\n      ${pre-commit-check.shellHook}\n    '';\n  };\n}\n```\n\n#### `pre-commit`\n\n[`pre-commit`](https://pre-commit.com/) can also be used directly:\n\n1. Make sure that you have the `pre-commit` command:\n\n    ```console\n    $ pre-commit --version\n    pre-commit 3.7.1\n    ```\n\n2. Make sure that you’re in your Git repo:\n\n    ```console\n    $ cd \u003cpath-to-git-repo\u003e\n    ```\n\n3. Make sure that the `pre-commit` tool is installed as a Git pre-commit hook:\n\n    ```console\n    $ pre-commit install\n    pre-commit installed at .git/hooks/pre-commit\n    ```\n\n4. If you don’t already have one, then create a `.pre-commit-config.yaml` file.\n\n5. Add an entry for the `nixfmt` hook to your `.pre-commit-config.yaml` file:\n\n    ```yaml\n    repos:\n        - repo: https://github.com/NixOS/nixfmt\n          rev: \u003cversion\u003e\n          hooks:\n                - id: nixfmt\n    ```\n\n    If you want to use a stable version of `nixfmt`, then replace `\u003cversion\u003e` with a tag from this repo. If you want to use an unstable version of `nixfmt`, then replace `\u003cversion\u003e` with a commit hash from this repo.\n\n6. Try to commit a badly formatted Nix file in order to make sure that everything works.\n\n#### `git mergetool`\n\n`nixfmt` provides a mode usable by [`git mergetool`](https://git-scm.com/docs/git-mergetool)\nvia `--mergetool` that allows resolving formatting-related conflicts automatically in many cases.\n\nIt can be installed by any of these methods:\n\n- For only for the current repo, run:\n  ```\n  git config mergetool.nixfmt.cmd 'nixfmt --mergetool \"$BASE\" \"$LOCAL\" \"$REMOTE\" \"$MERGED\"'\n  git config mergetool.nixfmt.trustExitCode true\n  ```\n- For all repos with a mutable config file, run\n  ```\n  git config --global mergetool.nixfmt.cmd 'nixfmt --mergetool \"$BASE\" \"$LOCAL\" \"$REMOTE\" \"$MERGED\"'\n  git config --global mergetool.nixfmt.trustExitCode true\n  ```\n- For all repos with a NixOS-provided config file, add this to your `configuration.nix`:\n  ```nix\n  programs.git.config = {\n    mergetool.nixfmt = {\n      cmd = \"nixfmt --mergetool \\\"$BASE\\\" \\\"$LOCAL\\\" \\\"$REMOTE\\\" \\\"$MERGED\\\"\";\n      trustExitCode = true;\n    };\n  };\n  ```\n- For all repos with a home-manager-provided config file, add this to your `home.nix`:\n  ```nix\n  programs.git.extraConfig = {\n    mergetool.nixfmt = {\n      cmd = \"nixfmt --mergetool \\\"$BASE\\\" \\\"$LOCAL\\\" \\\"$REMOTE\\\" \\\"$MERGED\\\"\";\n      trustExitCode = true;\n    };\n  };\n  ```\n\nThen, when `git merge` or `git rebase` fails, run\n```\ngit mergetool -t nixfmt .\n# or, only for some specific files\ngit mergetool -t nixfmt FILE1 FILE2 FILE3\n```\n\nand some `.nix` files will probably get merged automagically.\n\nNote that files that `git` merges successfully even before `git mergetool`\nwill be ignored by \\`git mergetool\\`.\n\nIf you don't like the result, run\n```\ngit restore --merge .\n# or, only for some specific files\ngit restore --merge FILE1 FILE2 FILE3\n```\n\nto return back to the unmerged state.\n\n#### `nix fmt` (experimental)\n\n[nix fmt](https://nix.dev/manual/nix/latest/command-ref/new-cli/nix3-fmt) (part of the [`flakes` experimental feature](https://nix.dev/manual/nix/latest/development/experimental-features#xp-feature-flakes)) can be configured to use `nixfmt` by setting the `formatter` flake output to `nixfmt-tree` (assuming a `nixpkgs` flake input exists):\n\n```nix\n# flake.nix\n{\n  outputs =\n    { nixpkgs, self }:\n    {\n      formatter.x86_64-linux = nixpkgs.legacyPackages.x86_64-linux.nixfmt-tree;\n    };\n}\n```\n\n## Usage\n\n* `nixfmt \u003c input.nix` – reads Nix code from `stdin`, formats it, and outputs to `stdout`\n* `nixfmt file.nix` – format the file in place\n\n## Acknowledgements\n\n`nixfmt` was originally developed by [Serokell](https://github.com/serokell) and later donated to become an official Nix project with the acceptance of [RFC 166](https://github.com/NixOS/rfcs/pull/166).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnixos%2Fnixfmt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnixos%2Fnixfmt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnixos%2Fnixfmt/lists"}