dream2nix: a framework for turning language package managers into Nix derivations

The premise: a lockfile is not a build

dream2nix is a framework for automated Nix packaging for various language ecosystems, maintained under the nix-community organisation by DavHau, with the documentation at dream2nix.dev.

The problem it addresses is a specific and recognisable one. Every language ecosystem has its own package manager with its own lockfile, and a lockfile is a good thing: it pins versions, it records hashes, it is reproducible in the sense that everyone running the same command gets the same versions. What it is not is a build. Turning a lockfile into something you can put in a Nix store, with the right build inputs, the right system dependencies, the right setup hooks and the right outputs, is a manual and per-project exercise, and the result tends to be a pile of hand written derivations that nobody wants to maintain.

The topic tags name the intended scope: 2nix, dream-to-nix, lang2nix, nix, nixos, nodejs, package-management, reproducibility and rust. So the ecosystems in view are the ones where a language package manager is the source of truth for dependencies, and the goal is to take that source of truth and derive the Nix build from it.

The stated goal of the project is to create a standardized, generic, modular framework for automated packaging solutions, aiming for better flexibility, maintainability and usability. The word framework is the key one. dream2nix is not a single converter for one ecosystem, it is an attempt to be the layer that all such converters share.

The list of goals behind that is worth reading as a design brief, because it explains the shape of the repository. Modularity, customizability, maintainability, code de-duplication across 2nix solutions, a common UI across 2nix solutions, reducing the effort to develop new 2nix solutions, exploration and adoption of new nix features, and simplified updating of packages. Four of those are about the framework existing once rather than several times over, and one is about the packages themselves being updatable without a rewrite.

The goals list, and what a common UI across converters has to mean

The goals section is unusually explicit for a Nix ecosystem project, and it is a list of engineering objectives rather than features.

Modularity and customizability are the first two, and they are the ones that shape the repository layout. There is a lib/ directory for the shared library, modules/ for the Nix module system surface, pkgs/ for packages, overrides/ for per-package overrides, aliases/ for the alias mechanism, scripts/ for helper scripts, and misc/ for odds and ends. The dev-flake/ directory is for the development environment, and there is a shell.nix and a default.nix alongside the flake.nix, which is the usual arrangement for a project that wants to be consumable both as a flake and through a channel-like entry point.

Code de-duplication across 2nix solutions is the goal that explains the whole architecture. A 2nix solution, that is a converter from a language ecosystem to Nix, needs the same things: read a lockfile, resolve the dependency graph, fetch the sources with the right hashes, build a derivation with the right inputs, and expose outputs. If each converter reimplements that, you get a dozen slightly different implementations of the same fragile logic. If they share it, you fix a bug once.

A common UI across 2nix solutions is the user-facing half of the same idea, and it is the harder half. A shared internal library can be shared without a shared interface, but if the user interface is also shared then using the tool for Node is the same experience as using it for Rust, and, more importantly, the same configuration. That is what makes a framework different from a collection of tools, and it is why the goal is stated as a first class item.

Explore and adopt new nix features is the goal that keeps the framework current, and it explains the CHANGELOG.md and the dev-flake/ directory. A framework that falls behind the nix feature set becomes a framework people cannot use, so the goal is to use dream2nix as a vehicle for trying new Nix features out.

Simplified updating of packages is the one that matters most in practice, because the alternative to automating packaging is hand maintaining a derivation forever. If the framework can regenerate a derivation from a lockfile, then updating a package is a matter of bumping the lockfile rather than editing a derivation by hand.

The unstable warning, and the drv-parts refactor

The README opens with a warning that is more specific than most warnings, and it should be read before anything else.

The text says dream2nix is unstable software, that while simple UX is one of the main focus points, the APIs are still under development, and to expect changes that will break your setup. That is a strong statement for a project with a documentation site, a changelog and years of history, and it is worth taking at face value rather than reading as boilerplate.

The reason for the instability is stated immediately after, in the legacy section. Dream2nix is currently in the process of being refactored to make use of drv-parts, not all features and subsystems are migrated yet, and if you prefer to continue using the makeFlakeOutputs interface you should refer to the legacy branch of the repository.

So there are two supported states right now. The main branch is the drv-parts based version, which is where the work is, and the legacy branch keeps the makeFlakeOutputs interface working. The phrase not all features and subsystems are migrated yet is the important qualifier, because it means the legacy branch is not simply an old version, it is a branch where the framework still works as a whole.

That is an unusual maintenance posture and it is a deliberate one. Rewriting a framework around a different derivation-building model is the kind of change that either happens with a clean break or not at all, and a project that is honest about the instability is better placed than one that pretends the interface is stable while it is moving underneath you.

The practical consequences for a user are concrete. Pin a commit rather than tracking the branch, and decide deliberately which interface you are targeting. If your package set depends on features that have not been migrated, you are in the legacy branch and you should read the CHANGELOG.md to see what has moved. If you can live with the new model, main is where the fixes land.

The migration is also visible in the history. The presentations list starts with a 2023 talk titled dream2nix based on drv-parts, followed by a 2021 original dream2nix presentation whose examples are noted as outdated. So the drv-parts approach is not new work, it is a couple of years old, and the 2021 material is what the legacy branch corresponds to.

The operational surface around the code

The parts of the repository that are not the framework itself are worth mapping, because they tell you what kind of contribution the project can accept and what it expects from a user.

There is a flake.nix and a flake.lock for the package itself, a default.nix and a shell.nix as the non-flake entry points, and a dev-flake/ directory for the development environment. That four-way arrangement is a common pattern in the Nix community for projects that want to be consumable as a flake, as a channel-style tarball and as a development shell, and it is the difference between a project that is usable by nixpkgs contributors and one that is not.

The tests/ directory and the treefmt.toml are the other two signals. A formatter configuration means the codebase is kept in a consistent style by a tool rather than by review, and a test directory means the framework has a suite rather than only examples. The .mergify.yml handles merges automatically, which for a project with outside contributors through Hacktoberfest is how you avoid a maintainer becoming a merge bottleneck.

The aliases/ and overrides/ directories are the parts of the design that are most interesting to a user, because they are the two escape hatches. An alias mechanism is how you point an existing Nix package name at a different implementation, which is the thing you need when you want the ecosystem's package but built your way. Overrides are how you patch a specific derivation without forking the whole framework, which is the thing you need the first time a package needs one extra build flag. The presence of both, as separate directories, says the framework treats divergence from upstream as a first class case rather than an exception.

The lib/, modules/, pkgs/ and scripts/ directories then hold the actual machinery, and docs/ holds the documentation that the dream2nix.dev site is built from, with a getting started guide linked as the entry point.

For a user, the practical reading is that the project has invested in being a well-behaved member of the Nix ecosystem, with a flake, a dev shell, tests, formatting and automatic merges. The instability warning is about the API, not about the hygiene, and those are separate questions when you decide whether to depend on it.

Funding, community and how the project is maintained

The funding section tells you something about the project's shape that a changelog does not.

The project was funded through the NGI Assure Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology, under grant agreement No 957073. Applications are still open and the README links to the application page, and the project says that if your organisation wants to support it with extra funding in order to add support for more languages or new features, you can contact one of the maintainers.

That funding structure is a good indicator of the kind of project this is. It is infrastructure work whose beneficiaries are many and whose costs are borne by a few, which is exactly the profile that public-interest funding programmes exist to address, and the framing of new language support as something an organisation can fund on top of the base grant is honest about the fact that the goal list is longer than the core team's capacity.

The community channels are small and specific. There is a Matrix chat room on the nixos.org homeserver, and the README notes that the project is released through the nix-community organisation, which is the shared GitHub organisation for Nix community projects rather than a personal namespace. The maintainer is credited in the repository description itself, as maintainer=@DavHau, and the Hacktoberfest topic tag indicates it takes outside contributions through that programme.

The repository layout reflects a project with real contributors rather than a single author. There is a .mergify.yml for automated merge handling, a .envrc for direnv, a treefmt.toml for formatting, a tests/ directory, a dev-flake/ directory for the development environment, and an examples/ directory with three distinct example projects: a repo with packages, a repo with packages as a flake, and a packages example. Those three are a deliberate spread, because they show the same idea in three shapes, and the fact that a flake-based example exists alongside the non-flake one tells you both entry points are supported.

The repository is not archived, the last push was on 2026-08-19, and there are no GitHub releases, so the version reference is the commit rather than a tag. For a project in the middle of a refactor, that is the right way to consume it anyway.

Editorial conclusion

dream2nix fits a Nix user who wants to package a project from a language ecosystem that nixpkgs does not carry, and who is prepared to pin a commit and expect the interface to move. It is the wrong tool if you need a stable API, because the project states outright that changes will break your setup, and it is the wrong tool if the package you need already has good nixpkgs coverage, since automating a packaging job that already exists buys little. Before adopting, read the warning at the top of the README, decide whether the drv-parts based main branch or the legacy branch with makeFlakeOutputs suits you, and look at the examples directory to see how much configuration a real project needs.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. nix-community/dream2nix on GitHub
4. Project website
5. README