flake-parts brings the NixOS module system to flakes themselves.

A flake.nix is configuration, and configuration is what the module system is good at. Where NixOS used modules to stop configuration.nix from becoming one enormous file of glue, flake-parts does the same for flake.nix: outputs become options, files become modules, and third parties can ship modules that plug straight into your flake.

It is deliberately not a monorepo trying to absorb all of open source. It is a small core — the attributes that constitute a flake — that other repositories build on, plus an ecosystem of modules you opt into.

Features:

mkFlake is thin. Stripped down, it is:

That is the whole trick. Everything you know about NixOS modules applies verbatim: imports, options, config, mkIf, mkDefault, mkForce, merging, type checking, _module.args. The class = "flake" tag means the module system will refuse a NixOS module accidentally imported into your flake, and vice versa.

The set of "known" flake outputs (packages, checks, apps, devShells, formatter, overlays, nixosConfigurations, …) are just options declared by the built-in modules. Anything not declared still works — flake has a freeform type — but only declared attributes can be merged across modules.

This is the central idea, and the reason perSystem exists.

Flake outputs are indexed attribute first, system second:

But when you are writing a project, you think system first, attribute second — "for this system, here are my packages, my checks, my shell":

Swapping those two indices is called transposition, and flake-parts does it for you:

Declaring transposition.foo = { }; adds, in pseudo-code:

Note the second line. Transposition also defines the reverse operation, and that reverse is exactly where inputs' and self' come from. inputs'.foo.packages.bar is not special syntax — it is inputs.foo.packages.${system}.bar with the system index already peeled off by perInput.

So a flake-parts module that wants to add a new per-system output does not write forAllSystems — it declares a perSystem option and a transposition, and both directions come for free.

Other templates: #package (a flake around one package), #multi-module (split across files), #unfree.

Add the input, then slide mkFlake between your outputs function head and its body:

mkFlake takes two arguments: an attrset of "how to evaluate", and the module itself.

Modules are functions, and flake-parts passes them arguments. Top-level and perSystem get different sets — mixing them up is the most common beginner error.

The ' is pronounced prime.

self, inputs, getSystem, withSystem and moduleWithSystem are deliberately not available in perSystem. flake-parts installs throwing stubs for them, so instead of attribute missing you get a hand-written error explaining that you probably wanted self'/inputs', or the top@ pattern:

The module system uses builtins.functionArgs to decide which arguments to pass, so only explicitly named parameters exist:

This is not an oversight. Nix evaluates the argument of args@{ foo, ... }: strictly, before the function body — but the module system cannot know the full set of module arguments until it has evaluated the modules, which requires calling them. functionArgs breaks the cycle.

If you genuinely need everything, perSystem (and only perSystem) exposes config.allModuleArgs.

The list of systems to enumerate in output sub-attributes. Everything in perSystem is instantiated once per entry.

The nix-systems ecosystem (inputs.systems) lets consumers override this: systems = import inputs.systems;.

A module, evaluated once per system, whose options mirror the flake outputs with the <system> level removed.

Because perSystem is a real module, you can use imports, mkIf, and declare your own options inside it.

Everything that is not per-system. It is an RFC42-style freeform submodule: declared options merge properly, undeclared attributes are passed through as-is but may only be defined once.

Defining an undeclared attribute in two modules produces a pointed error:

The fix is to load a module that declares it, or declare it yourself.

Setting debug = true; adds debug, allSystems and currentSystem to the flake outputs. See Debugging.

The value mkFlake actually returns. By default it equals flake. The optional touchup module lets you diverge the two — useful to hide an attribute from nix flake check while keeping it visible to your own modules.

Machine configurations, deployments and overlays are not per-system, but they constantly need per-system values. Three tools, same underlying data:

withSystem is usually the one you want, because you also get pkgs, inputs' and self', not just config.

moduleWithSystem does the same for a module you export, without introducing a global:

This is the headline feature, and it has one non-obvious consequence: the moment you move code into another file, you lose the lexical scope of flake.nix. No more inputs, no more let bindings from the outer file.

A plain flake module still gets the module arguments, which covers most cases:

But when the separate file is a NixOS module (a different module system evaluation entirely), the flake-parts arguments are gone. Two solutions:

Write a thin inline module that bridges the two scopes, and turn the missing variable into an option:

Make such options as specific as possible — foo.package, not foo.flake. Most modules need only one or two.

importApply imports a file containing a function to a module and applies it, letting you pass extra values across the file boundary:

Unlike specialArgs, this survives being imported into someone else's flake, so it is the right choice for modules you publish.

If you both export a flake module and use it locally, you cannot write imports = [ config.flake.flakeModules.default ] — importing from self could change self, which is infinite recursion. Bind it in a let and reference the binding twice:

The genuinely interesting property of flake-parts is that a module can add new kinds of flake output, not just configure existing ones. This is why the ecosystem modules feel like language extensions rather than libraries.

If it is project-specific, just set it. flake is freeform:

For anything reusable, declare it — you get documentation, type checking and merging. This is disko's entire flake-parts module:

That is it. Importing inputs.disko.flakeModules.default makes diskoConfigurations a first-class, mergeable flake output that the disko CLI then discovers.

For something that varies by system, use mkTransposedPerSystemModule — it declares the perSystem option, the flake.<name>.<system> output, and the perInput reverse mapping in one go. flake-parts' own bundlers module is exactly this:

For options that live under perSystem without being transposed, use flake-parts-lib.mkPerSystemOption — plain perSystem = { options = …; } works but is invisible to documentation generation.

Consumers write imports = [ inputs.you.flakeModules.default ];. Single-module flakes should use the name default.

The generalised form. The outer attribute names the module class, so one flake can publish NixOS modules, Home Manager modules, flake modules and class-agnostic modules through one uniform interface:

generic declares no class, so those modules can be imported into any module system evaluation.

dendritic is a convention built on top of flake.modules, popular enough to be worth knowing by name.

The rule is: every Nix file except entry points is a top-level flake-parts module.

So modules/monitoring.nix might define a NixOS module, a Home Manager module, a package and a check all at once — everything that "monitoring" means — instead of scattering those four fragments across four directories.

The pattern does not technically require flake-parts (plain lib.evalModules works), but flake-parts is the usual host.

flake.nixosConfigurations is an ordinary option; the interesting question is where pkgs comes from.

Simplest. perSystem keeps a separate, unaware pkgs.

One Nixpkgs for devShells, packages and machines. readOnlyPkgs stops anything downstream from silently re-instantiating it.

Set debug = true;, then explore in the repl — including options that are internal and never reach the outputs.

The .files / .declarations trick is the fastest way to answer "which module set this?" in a flake with a dozen imports.

Roughly forty flake modules are published and documented at flake.parts. Importing one is always the same shape:

What makes them worth the trouble is that most do not merely set packages or devShells — they declare new option paths and new flake outputs, so your flake grows a vocabulary for the domain.

Others worth knowing: haskell-flake, rust-flake, nix-cargo-integration, pkgs-by-name-for-flake-parts, hercules-ci-effects, nix-unit, ez-configs, easy-hosts, mission-control, agenix-shell, actions.nix.

Three imports produce nix fmt, a formatting check, working git hooks, and nix run .#dev bringing up the stack — with no glue code.

Not enabled by default; import from inputs.flake-parts.flakeModules.<name>.

flake-parts uses partitions on itself: its checks, devShells and tests come from a separate ./dev flake, so importing flake-parts never fetches its development inputs.