Stop wiring Nix dependencies by hand. Declare them once and Mana resolves the whole transitive tree, deduplicates it, and injects each into your project.
{ name = "<YOUR PROJECT>"; entrypoint = ./entrypoint.nix; dependencies = { nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable"; }; shares = [ "nixpkgs" ]; # transitive deps use YOUR nixpkgs }
mana update does the rest: resolves the full tree, pins it in lock.json, and injects each dependency into your build.
What you author
# '<YOUR PROJECT>' - Manifest # -------------------- { name = "<YOUR PROJECT>"; # description = ""; entrypoint = ./entrypoint.nix; dependencies = { nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable"; }; # Share these dependencies with all transitive dependencies. # Libraries that also depend on nixpkgs will use YOUR version. shares = [ "nixpkgs" ]; }
Resolve + lock — fetch the transitive graph and pin it.
$ mana update
Updating all dependencies
lock.json updated
Runs check, evaluates scripts/update.nix → next_lock.json, verifies it parses, then mvs it to lock.json. No args updates everything; mana update nixpkgs updates one dependency.
The resolved, pinned graph — { deps, sources }.
{
"deps": {
"": {
"nixpkgs": "/nixpkgs"
}
},
"sources": {
"/nixpkgs": {
"args": {
"owner": "nixos",
"ref": "nixos-unstable",
"repo": "nixpkgs",
"type": "github"
},
"locked": {
"lastModified": 1775710090,
"lastModifiedDate": "20260409044810",
"narHash": "sha256-ar3rofg+awPB8QXDaFJhJ2jJhu+KqN/PRCXeyuXR76E=",
"rev": "4c1018dae018162ec878d42fec712642d214fdfa",
"shortRev": "4c1018d"
}
}
}
}
sources maps lockKey → { args, locked }. deps maps parentKey → { name → lockKey } — the root parent is "". A lockKey is the dependency's tree path (/A, /A/B); / is banned in names so keys never collide. Two deps with the same narHash collapse to one source — that is the deduplication.
Evaluation entry point — selects enabled groups.
(import ./nix/importer.nix) {
# evaluation arguments
#
# groups = [ "eval" "dev" ]
# : Enabled evaluation groups, see README.md
# : default = [ "eval" ]
}
Build a target with nix build -f default.nix hello. Default enabled groups: [ "eval" ].
Resolve + inject — the shim mana writes and upgrades for you.
# Import the entrypoint, passing resolved deps as args importEntrypoint = f: if builtins.isFunction f then f (builtins.intersectAttrs (builtins.functionArgs f) scope) else f; … scope = importNode { nodeLockKey = ""; # Start from "root" nodeManifest = normalizeManifest { } manifest; nodeGroups = groups; }; f = import manifest.entrypoint; in f (builtins.intersectAttrs (builtins.functionArgs f) scope)
Walks deps, fetchTrees each sources entry, imports each entrypoint, and injects only the arguments a function declares — via builtins.intersectAttrs (functionArgs f) scope. A dependency outside every enabled group throws on access, listing the groups that would include it.
debug = true to tracetrace: [mana] <root> groups: eval, dev deps: nixpkgs, treefmt-nix trace: [mana] <root>/nixpkgs [raw] trace: [mana] <root>/treefmt-nix [entrypoint: entrypoint.nix] trace: [mana] /treefmt-nix groups: eval deps: nixpkgs trace: [mana] /treefmt-nix/nixpkgs [raw]
[raw] — entrypoint = null; returns the source path, no import[custom: path] — consumer overrides the entrypoint[entrypoint: path] — dependency's own entrypoint from its mana.nix[default.nix] — no mana.nix; falls back to default.nixReceives the resolved dependencies as function arguments.
# manifest dependencies, injected by the nix/importer.nix # ↓ dependencies controlled by mana { nixpkgs }: # ↓ your parameters {system ? builtins.currentSystem, ... }: let pkgs = nixpkgs { inherit system; }; in { hello = pkgs.hello; # ...more of your own stuff }
Build output — pkgs.hello, fully resolved.
$ nix build -f default.nix hello $ ./result/bin/hello Hello, world!
By default every dependency re-locks its own nixpkgs. shares unifies the subtree; pins protects a dependency from an ancestor's share.
shares = [ "nixpkgs" ] at the root overrides nixpkgs across its entire subtree — A, B and C all resolve to root's /nixpkgs (unstable). It does not touch root's own version.
pins = [ "nixpkgs" ] at B protects its own nixpkgs@26.05 from the ancestor share. Below the pin the share no longer reaches: C keeps /A/B/C/nixpkgs (25.11).
A dependency is fetched only when its group is enabled — so groups double as feature flags. Gate a heavy, optional dependency behind its own group (say, a pinned CUDA toolkit); only builds that enable it pay the download. One entrypoint.nix serves every group; accessing a disabled dependency throws.
groups = {
eval = { nixpkgs = [ ]; };
dev = { treefmt-nix = [ ]; };
cuda = { cudatoolkit = [ ]; };
};