Debugging broken builds

When debugging the creation of a new package, or a currently failing one, seem to be lacking the most basic debug tools.
It feels like this should be something entirely trivial, but I still haven’t figured out how to do it. What am I missing?

In particular, say I am working (as I just was) on python-redis-lock.

To see whether the package builds, I run:

nix-build -I nixpkgs=/home/klaas/nixpkgs/master/ -A pkgs.python3Packages.python-redis-lock '<nixpkgs>'

This fails with an error message in the tests. This error message points me in some general direction, but I’d like to e.g. put a breakpoint in the failing tests (in Python: import pdb; pdb.set_trace()) to really dive into it.

What I want, is to be placed in an environment just like the failing build, and to have (or be able to get, using commands) an overview of the steps that the actual build would take.

How can this be achieved?




For random ad-hoc debugging like pdb one possible way is to use nix-shell to get an interactive and isolated environment going. For this you could use the existing derivations from nixpkgs.

One small caveat with this is that such a derivation usually requires minor adjustments as they depend on being called other parts of nixpkgs (I am not aware of an automatic/out of the box method to do that), but often it’s enough to replace the argument list with with import <nixpkgs>{};

Once you are dropped into the resulting shell, you should be able to invoke the code and tests manually etc.

Edit: There is also a useful thread about nix-shell workflows: What is the best dev workflow around nix-shell?

There is also breakpointHook:


Additionally it is worth to point out that both nix-shell and nix-build take a --keep-failed / -K option (which is nicely documented in the manual in the Common Options section). If you use it, builder is going to keep your package /tmp/nix-build-* build directory in the case of a failure. The exact build path is printed out to the console.


I want to also add a few details regarding breakpointHook. It is a really powerful debug hook by @Mic92.

It is enough to put pkgs.breakpointHook into your buildInputs to get it working. In the case of a failure there is an exact “connection” command printed out to the console. You can use this command (cntr) to attach a shell into the build environment. To use it you have to be able to run sudo along with cntr (so you should install cntr package before ;-)).

You can find more interesting details in the @Mic92 NixCon presentation:


That stands as one of my fav technical presentations, it’s a real gem and very useful.

1 Like