Getting started with flakes

Last updated 2026-05-30 · 2 min read

Nix flakes make dependency management of modules and packages much easier.

Quick start from template #

The fastest way to get started is with the terranix flake template:

nix flake init --template github:terranix/terranix-examples

This creates a flake.nix and config.nix you can build right away.

A minimal flake.nix #

Extending Getting started, this minimal flake defines your terranix resources in config.nix:

{
  inputs = {
    terranix.url = "github:terranix/terranix";
    terranix.inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs = { terranix, ... }:
    let
      system = "x86_64-linux";
    in
    {
      defaultPackage.${system} = terranix.lib.terranixConfiguration {
        inherit system;
        modules = [ ./config.nix ];
      };
    };
}

nix build #

Instead of terranix config.nix > config.tf.json, you can run nix build -o config.tf.json:

nix build -o config.tf.json
tofu init
tofu apply

Use terraform or tofu if you installed either of them plainly.

nix run #

You can create Nix flake apps that let you run:

  • nix run
  • nix run .#apply
  • nix run .#destroy
{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs";
    terranix.url = "github:terranix/terranix";
    terranix.inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs = { self, nixpkgs, terranix, ... }:
    let
      system = "x86_64-linux";
      pkgs = nixpkgs.legacyPackages.${system};
      terraform = pkgs.terraform;
      terraformConfiguration = terranix.lib.terranixConfiguration {
        inherit system;
        modules = [ ./config.nix ];
      };
    in
    {
      # nix run ".#apply"
      apps.${system} = {
        apply = {
          type = "app";
          program = toString (pkgs.writers.writeBash "apply" ''
            if [[ -e config.tf.json ]]; then rm -f config.tf.json; fi
            cp ${terraformConfiguration} config.tf.json \
              && ${terraform}/bin/terraform init \
              && ${terraform}/bin/terraform apply
          '');
        };

        # nix run ".#destroy"
        destroy = {
          type = "app";
          program = toString (pkgs.writers.writeBash "destroy" ''
            if [[ -e config.tf.json ]]; then rm -f config.tf.json; fi
            cp ${terraformConfiguration} config.tf.json \
              && ${terraform}/bin/terraform init \
              && ${terraform}/bin/terraform destroy
          '');
        };
      };

      # nix run
      defaultApp.${system} = self.apps.${system}.apply;
    };
}

Writing terranix modules #

You can scaffold a new terranix module with:

nix flake init --template "github:terranix/terranix-examples#module"

A terranix module flake should provide the following outputs:

  • terranixModules.<name> — individual modules
  • terranixModule — all terranixModules combined

The function lib.terranixOptions can render an options.json for your module, which is useful for generating documentation. See the terranix-module-github repository for an example.

For more on the module system itself, see the Modules page.

As a next step, read terranix and flake modules to use flake-parts to manage terranix configurations declaratively

Edit this page on GitHub →