Alejandra 💅

The Uncompromising Nix Code Formatter

Try it on your browser! here

Features

• ✔️ Fast

  It's written in Rust and formats Nixpkgs in just a few seconds. [^benchmark-specs]

• ✔️ Powerful

  We define a comprehensive style for all possible combinations of the Nix expression language.

• ✔️ Reliable

  High coverage, battle tested.

  From Nix's eyes, code is just the same. [^semantic-changes]

• ✔️ Beautiful

  Beauty is subjective, right?

  We started from the original style of Nixpkgs, and then we applied the feedback of developers who have used Nix at scale for several years, producing a very well-grounded style guide. For everything else, some pieces of the style are configurable.

• ✔️ Transparent

  You won't notice the formatter after a while.

  Humans care about the content, machines about the style!

• ✔️ Native

  We integrate with common code editors and workflows:

  • Visual Studio Code
  • Neovim
  • Vim
  • GNU Emacs
  • Doom Emacs
  • Pre-commit
  • Pre-commit-hooks.nix

Getting started

On the web editor

Please visit: kamadorueda.github.io/alejandra.

Prebuilt binaries

You can download a binary for your platform:

• aarch64-unknown-linux-musl
• x86_64-unknown-linux-musl

Make it executable ($ chmod +x) and run Alejandra with:

$ ./alejandra --help

or:

$ /path/to/alejandra --help

From Nixpkgs

Please visit: search.nixos.org/packages?query=alejandra.

Nix installation

• Nix stable:

  $ nix-env -ivf https://github.com/kamadorueda/alejandra/tarball/4.0.0
  

• Nix with Flakes:

  $ nix profile install github:kamadorueda/alejandra/4.0.0
  

Then run Alejandra with:

$ alejandra --help

NixOS installation

• Nix stable:

  let
    alejandra =
      (import (builtins.fetchTarball {
        url = "https://github.com/kamadorueda/alejandra/tarball/4.0.0";
        sha256 = "0000000000000000000000000000000000000000000000000000";
      }) {})
      .outPath;
  in {
    environment.systemPackages = [alejandra];
  }
  

• Nix with Flakes:

  {
    inputs = {
      nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
  
      alejandra.url = "github:kamadorueda/alejandra/4.0.0";
      alejandra.inputs.nixpkgs.follows = "nixpkgs";
    };
  
    outputs = {alejandra, nixpkgs, ...}: {
      nixosConfigurations = {
        example = nixpkgs.lib.nixosSystem rec {
          # We support: aarch64-darwin, aarch64-linux, i686-linux, x86_64-darwin, x86_64-linux
          system = "x86_64-linux";
  
          modules = [
            {
              environment.systemPackages = [alejandra.defaultPackage.${system}];
            }
            # Import your other modules here
            # ./path/to/my/module.nix
            # ...
          ];
        };
      };
    };
  }
  

From Homebrew

$ brew install alejandra

(experimental) Configuration Options

You can configure Alejandra through a file named alejandra.toml. This file will be automatically detected if found in the same directory where Alejandra is being run from, or you can tell Alejandra to use a different location by using the --experimental-config ./path/to/alejandra.toml flag in the CLI.

You can find a full configuration file and the supported options here: alejandra.toml.

Cool libraries

• NixEL
• Santiago
• rnix-parser

Alternatives

• NixOS/nixfmt
• serokell/nixfmt
• nixpkgs-fmt

Versioning

We use semver to version Alejandra.

Our public API consists of:

• The formatting rules (a.k.a. the style).
• The CLI tool ($ alejandra), command line flags, positional arguments, exit codes, and stdout.

With the exception of those explicitly marked as "experimental".

Changelog

Please read: CHANGELOG.

Contributors

The following people have helped improving Alejandra.

Thank you ❤️

Bobbe, Connor Baker, Daniel Bast, David Arnold, David Hauer, esf, Fabian Möller, Florian Finkernagel, Jamie Quigley, Joachim Ernst, Johannes Kirschbauer, Jörg Thalheim, Kevin Amado (Email, LinkedIn), Loïc Reynier, Matthew Kenigsberg, Michael Utz, Mr Hedgehog, Nathan Henrie, Norbert Melzer, Pablo Ovelleiro Corral, Patrick Stevens, Piegames, Rebecca Turner, Rehno Lindeque, Rok Garbas, Ryan Mulligan, Thomas Bereknyei, Tobias Bora, Tristan Maat, UserSv4, Victor Engmark, Vincent Ambo, Vladimir Fetisov, and Yorick van Pelt.

Footnotes

[^benchmark-specs]: Running on a machine with:

- CPU: 4 physical, 4 logical, 11th Gen Intel(R) Core(TM) i7-1165G7 @ 2.80GHz
- MHz: from 400 to 4700 MHz
- BogoMips: 5606.40
- Cache L3: 12 MiB

Using:

```bash
# x86_64-unknown-linux-gnu
$ time alejandra --threads $threads /path/to/nixpkgs
```

Results:

| $threads | Seconds |
| :------: | :-----: |
|    1     |   45    |
|    2     |   25    |
|    4     |   14    |

[^semantic-changes]: The methodology to claim this is:

1.  Checkout [Nixpkgs](https://github.com/nixos/nixpkgs) and run:

    ```bash
    $ nix-env -qaf . --drv-path --xml > before
    ```

1.  Now format with Alejandra and run:

    ```bash
    $ nix-env -qaf . --drv-path --xml > after
    ```

As of 2022-06-22,
there are 41 differences in a set of 38109 derivations
because of things like this:

```
goDeps = ./deps.nix;
```

Since `./deps.nix` was also formatted
you get a semantical difference.

This is something that should be solved on Nixpkgs
and not a bug in Alejandra.
For example:

- https://github.com/NixOS/nixpkgs/pull/178378
- https://github.com/NixOS/nixpkgs/pull/157760