Archive nixos-generators in favor of nixos-rebuild build-image

[phaer]

tl;dr: replace with upstreamed implementation, drafted because manual links won't work before 25.05 is stable.

I deliberately delete the code for the last commit so that people who just run flake update notice the breakage. If they want to continue nixos-generators as-is for the time being, they could pin the last commit before this PR.

---

Starting with NixOS 25.05, most of nixos-generators has been upstreamed into nixpkgs.

So we believe it's time to retire nixos-generators, a good 7 years after its initial commit and after countless built images.
Please let us know if you run into any trouble, such as missing features, during the migration.

The main, user-visible difference is the new nixos-rebuild build-image command, which replaces the venerable nixos-generate.
Check its manual section or the updated README on how that works.

---

related upstream PRs
NixOS/nixpkgs#347275 (merged, see links in description)
NixOS/nixpkgs#398556
NixOS/nixpkgs#397330

[mayl]

Wow, big news!

I notice that your manual link links to the stable branch where nixos-rebuild build-image is not yet defined. I found the documentation in the unstable manual, but it's quite sparse and I'm still trying to fully understand how it is meant to work.

Does this new method support something similar to nixos-generators formatConfigs where per-format configuration can be added?

Does it support a similar method for adding custom formats without having to fork nixpkgs?

Sorry if the answers to these questions are obvious, but part of the reason I'm bringing them up is that one of the benefits of nixos-generators for me as a user has honestly been just the many examples in the readme.md here to pull from. I would assume the above use cases are supported, but a couple examples in the manual would go a long way to help keep parity with nixos-generators IMO.

[phaer]

I notice that your manual link links to the stable branch where nixos-rebuild build-image is not yet defined.

Yes, this won't be ready to merge before 25.05 will be released, and those links should be good. It sadly does not seem possible(?) to link to a specific release, just stable/unstable.

Does this new method support something similar to nixos-generators formatConfigs where per-format configuration can be added?

Thanks for the question, I should mention this in the docs here:

There's an option called image.modules, defined in nixos/modules/image/images.nix. It's an attribute set mapping names to nixos modules, see i.e. the pre-defined imageModules in the same file. So if you do something like

  image.modules.my-fancy-format = { pkgs, config, ...}: {
    environment.systemPackages = [ pkgs.fancy-format-agent ];
  };

you should be able to build that with either the config.system.build.images.my-fancy-format attribute or nixos-rebuild build-image --image-variant my-fancy-format.

Does it support a similar method for adding custom formats without having to fork nixpkgs?

Ah, I think i mixed up the question and answered that one in the first and the first was actually about customization of existing "formats" ("variants" in nixpkgs)?

If so, that will soon be in the manual - you can extend existing variants in the same way you declare new ones:

  image.modules.linode = {
    boot.loader.systemd-boot.enable = lib.mkForce false;
  };

Hope that answers your question, happy about any feedback!

[Mic92]

I think and evaluation warning is better than deleting everything in case we have to undo this. It also provides more context on what is happening rather than just breaking everything.

[mayl]

Thanks for the clarifications, I should try the new system out sometime soon to be sure I get it, but I think I mostly understand how it's mean to work.

I don't mean to harp on this too much, but I'll just put a plug in one more time for a full worked example somewhere in the documentation whether it's in the manual, or linked to it or a flake template that the manual references or whatever. I've used nix for a few years now and I'm reasonably confident I'll be able to go through your docs in the manual and the source in nixpkgs to figure out how to make an image with this new system. But that's because even though I'm definitely not an expert, I do 1) know the nix configuration language 2) have a general (albeit incomplete) idea for how nixpkgs works 3) understand the module system and it's schema 4) understand how to setup a flake and what it's schema is 5) understand the nix CLI for building things from a flake and probably a couple other pieces of nix trivia I've picked up along the way. Learning about all those things is important and valuable, but is also a difficult on-ramp to using the new system even for motivated new users. One thing I've appreciated and learned a lot from with nixos-generators, is that there were working examples to start from and I think it would be nice to carry some of that forward if it's possible.

What do you think the best way to publish an example is? Should I try to add something to the templates repo and get it linked in the manual?

[phaer]

I think and evaluation warning is better than deleting everything in case we have to undo this. It also provides more context on what is happening rather than just breaking everything.

I am happy to reconsider this and just do eval warnings for at least one release.
When chatting with @Lassulus, we had talked about archiving nixos-generators. This assumes that the upstreaming effort is good enough to cover the vast majority of use-cases and that fixes could be applied upstream, to nixpkgs, with at least comparable speed and ease to nixos-generators.

To ensure this we/I need to at least provide more in-depth documentation and examples and maybe code changes. I'll continue working on this until undrafting this PR, but i am not at all opposed to just the eval warning and can do that :)

Can that eval state that nixos-generators is deprecated in favor of the upstreamed features or do you see long-term value in keeping nixos-generators?

[phaer]

Thanks for the clarifications, I should try the new system out sometime soon to be sure I get it, but I think I mostly understand how it's mean to work.

Please do! Now is an excellent time to pull the latest nixos-unstable and build images.

I don't mean to harp on this too much, but I'll just put a plug in one more time for a full worked example somewhere in the documentation whether it's in the manual, or linked to it or a flake template that the manual references or whatever.

There's now at least an example to customize an existing image (as well as a mention of the sub-command and the most important module options) in https://nixos.org/manual/nixos/unstable/#sec-image-nixos-rebuild-build-image.

I am working on a full example in the manual. Happy to add a full flake example here, but I was under the impression that the nixos manual still avoids mentioning flakes? :(

There's also examples for images build with nixos repart-integration as well as downstream integration with disko needed in the future.

I've used nix for a few years now and I'm reasonably confident I'll be able to go through your docs in the manual and the source in nixpkgs to figure out how to make an image with this new system.

That's a good thing! At this point it probably is still an intermediate feature.

But that's because even though I'm definitely not an expert, I do 1) know the nix configuration language 2) have a general (albeit incomplete) idea for how nixpkgs works 3) understand the module system and it's schema 4) understand how to setup a flake and what it's schema is 5) understand the nix CLI for building things from a flake and probably a couple other pieces of nix trivia I've picked up along the way.

That's a very apt description why at least custom variants are an intermediate to advanced feature.

Add to that two nixos-rebuild(-ng) implementations that are currently used (one bash, one python), different ways to build images (make-disk-image.nix, systemd-repart) and a dozen heterogeneous image modules with custom options and it quickly becomes complicated to write good interfaces for it.

So thanks for the feedback, happy about more!
I'll polish documentation and examples up a bit for the 25.05 release and beyond.

Learning about all those things is important and valuable, but is also a difficult on-ramp to using the new system even for motivated new users. One thing I've appreciated and learned a lot from with nixos-generators, is that there were working examples to start from and I think it would be nice to carry some of that forward if it's possible.

Absolutely!

What do you think the best way to publish an example is? Should I try to add something to the templates repo and get it linked in the manual?

That's one thing I am not super comfortable with yet. I think it the depends on the nature of the example. I try to just integrate basic, non-flake ones straight into the nixos manual. Then maybe some more in-depth technical stuff about the options in the nixpkgs manual?

I hadn't thought about the official nixos templates for flake examples yet tbh, but that could be a great place - let's discuss there!

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/nixos-rebuild-build-image-error-option-system-build-images-no-value-defined/63671/1

[ODAncona]

@phaer Hello,

I need to build a worker image for n kubernetes nodes and the only setting that change is the hostname. Therefore, I don't want to build n images for my n workers. I would prefer to have the option to keep the configuration.nix in the generated VM. What would be the canonical way to do this ? I saw people trying to do gitops and other just trying to nixos-rebuild switch on the generated VM and other that faced similar issues.

Is this functionality already implemented in nixos-rebuild build-image ? Or if it isn't possible, what would be the canonical way to edit configuration after generation on the VM ?