doc: Add Nix build notes #35375

nkaretnikov commented at 9:26 PM on May 25, 2026: none

This PR adds notes on how to create a development environment using the Nix package manager, by recommending the user to use bitcoin-dev-tools/bix.

Rationale

Nix simplifies dependency management, which is especially relevant on systems without recent packages. It also allows you to install different compiler versions and libraries with ease, which is great for testing and development.

Why not add a package recipe at the root of the repo

Adding a configuration file for a package manager is an opinionated change. It also requires extensive testing and needs to work for a variety of users. For now, it's proposed to just link to the Bix documentation and focus on improving that project. This helps users who want to use Nix, but doesn't put burden on the main project to maintain relevant configs.

doc: Add Nix build notes f79572c5a8

DrahtBot added the label Docs on May 25, 2026

DrahtBot commented at 9:26 PM on May 25, 2026: contributor

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Code Coverage & Benchmarks

For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/35375.

Reviews

See the guideline for information on the review process.

Type	Reviewers
Concept NACK	sedited
Concept ACK	ekzyis

If your review is incorrectly listed, please copy-paste <code></code> into the comment that the bot should ignore.

Fix typo e845928846

nkaretnikov marked this as ready for review on May 25, 2026

sedited commented at 9:38 PM on May 25, 2026: contributor

Thank you for your contribution. Some developers working on this project maintain https://github.com/bitcoin-dev-tools/bix , which defines a fairly comprehensive nix dev environment. I think the utility for documenting a slimmer setup, like done here, is rather limited, so I'm tending towards Concept NACK here.

nkaretnikov commented at 9:58 PM on May 25, 2026: none

@sedited Thanks for the quick reply! I simply was not aware of that project. If that's the preferred way of building using Nix, I think it should be linked in the documentation. AFAICT, there are no references to bix as of now. When I wanted to build Core, I followed the README at the root of the project and only found info for various OSes.

I've looked at their flake file. It's still somewhat "arbitrary" as it uses Clang and not GCC, for example. It's also way more complicated than the code I'm proposing here, which mainly aims to teach a person how to create their own env quickly.

What do you think would be the best way to proceed?

Do nothing, not add any documentation, and close this PR.
Document bix instead.
Extend the current document with a bix section.

I'm personally in favor of (3). Not because I've already written this, but because it's the most flexible:

It gives context on Nix for users who might be new
Points to a simple recipe that is easy to understand
Would point to a more realistic recipe that's maintained by developers, via bix
In the future, if more workflows related to Nix are created, it can be all listed there. For example, I mention in the doc how you can use Nix to swap between GCC and Clang, or do ASan builds. This can be provided later.

WDYT?

sedited commented at 10:05 PM on May 25, 2026: contributor

I think setting up a simple environment is pretty trivial. Anybody who is already motivated enough to read a nix documentation section, can probably do so with minimal effort anyway. Maybe @willcl-ark has an opinion on how and whether we should give some guidance to nix users.

nkaretnikov commented at 10:21 PM on May 25, 2026: none

Sure, happy to hear @willcl-ark's opinion on this. In general, I'm OK with this not being merged if people don't want this. Not trying to be pushy in any way, just trying to clarify.

I just think it is quite arbitrary not to include Nix if there are instructions on how to install via apt, etc. Yet Nix is a much more powerful tool allowing for use cases I mentioned above. So it's not simply about this basic recipe and more about having a place to collect future advanced use cases. But I'd be also happy to do so in my own repo somewhere.

I also could have waited and collected those locally and then submitting, but I'm worried that it'll turn a simple doc change into a monumental task and it never gets done. In my experience, small incremental steps are easier.

maflcko commented at 7:37 AM on May 26, 2026: member

I am also thinking if the existing doc/build-unix.md could be stripped down to remove Fedora, Alpine and Arch. The only difference is the name of the package manager program and possibly the names of the packages themselves.

If we want to keep them, a simple table with the package manager name and package name should be sufficient (with or without nix).

fanquake commented at 9:34 AM on May 26, 2026: member

Something Nix related in this repo could be useful, but the current text is too verbose. If somebody wants to learn about Nix, what it is, how it works, or how to install it, they can go to https://nix.dev/ or https://nixos.org/. We don't need to repeat documentation/context from those websites here, content in this repo should stay specific to Bitcoin Core.

willcl-ark commented at 12:29 PM on May 26, 2026: member

Yes I think we should consider carfeully what we want to add here, nix-wise, as there are many possibilites.

A build derivation (flake or default) could live at the root of the repo. Note that this is already in nixpkgs here in some form, although this can't easily be used to build a checked out tree. An in-tree (flake) version might look like this (ignoring the static packageSet which I was playing with).
a devShell/shell.nix. This is useful for developers, but we don't usually add tooling-specific stuff here which makes sense, as there are infinite numbers of tools.
We could also combine both of the above, into a package derivation and devShell

These might cater to different crowds; it's quite nice to say to users "to build the binary run nix build .". Devs may appreciate a standardised dev environment to use, as well as build functionality.

I suppose this comes down to "what problem are we trying to solve here".

I am also thinking if the existing doc/build-unix.md could be stripped down to remove Fedora, Alpine and Arch. The only difference is the name of the package manager program and possibly the names of the packages themselves.

In any case, I do like the idea of simpler table naming package manager and package names, and not repeating the instructions ~verbatim multiple times.

nkaretnikov commented at 5:11 PM on May 26, 2026: none

There are several comments and proposals, let me try to summarize them to make them actionable:

@sedited leans negative, has concerns about duplication of the Bix effort and the basic env being too simple.
@maflcko proposes to simplify the distro section of unix notes (potentially integrating Nix there), 👍 by @stickies-v.
@fanquake is positive on Nix notes but wants shorter text, 👍 by me.
@willcl-ark shares options on various build recipes we could add, likes the idea of a table for unix as well.

Comments to the above:

I would like to have Nix included because we have instructions for other package managers. The purpose of docs is to help people get started quickly. I'm okay with linking to Bix and dropping the simple shell.nix. Bix uses nix develop and a lockfile, so it should help with reproducibility. It also creates one space for Nix users to collaborate.
I'm okay with this in general, but I think it should be a separate PR. However, it needs to be done such that important context is not dropped. For example, there are useful comments there right now explaining why each dependency is needed.
Agreed on verbosity, will just link to upstream docs.
I would be glad if we had top-level build files, but they would need to be flexible enough to serve various use cases. It also endorses one particular package manager, which people might not want to do. I think it's better to focus on docs for now, there is very little downside or risk with adding them as opposed to code that needs to work and be tested. We cannot even agree on a simple doc change, the build recipes will be a huge discussion. I think it's better to focus on polishing Bix for now and having docs pointing there.

My refined proposal:

I will keep this file as separate and avoid refactoring the Unix distro section.
I will shorten the Nix description and point to the upstream docs instead.
I will remove the sample shell.nix file and link to Bix instead.
I will verify that Bix works as of now and allows me to build the project and run tests as with the original shell.nix file.

Could you please react with 👍 or 👎 to this proposal? If 👎 , please share why.

In general, I would like to make a small step to having better documentation instead of having a huge discussion about it. Let's make this first step and then we can separately discuss other things on other PRs. Again, not trying to be pushy, but it's very hard to make progress when we're discussing multiple things at the same time or have conflicting opinions. I hope that the plan presented above is a good compromise.

nkaretnikov marked this as a draft on May 26, 2026

Simplify Nix notes, link to Bix f11abe4f60

nkaretnikov marked this as ready for review on May 26, 2026

nkaretnikov commented at 6:39 PM on May 26, 2026: none

Simplified according to the refined proposal above, confirmed that Bix works as of today.

I think this is ready to be merged and looks way better than the original version.

nkaretnikov commented at 6:39 PM on May 26, 2026: none

Ah, one second, let me edit the PR description as well to match the new doc structure.

nkaretnikov commented at 6:47 PM on May 26, 2026: none

Updated, ready for review.

in doc/build-nix.md:14 in f11abe4f60 outdated

   9 | +Some Bitcoin Core contributors maintain
  10 | +[Bix](https://github.com/bitcoin-dev-tools/bix), which provides a Nix
  11 | +development environment. Refer to the Bix documentation on how to use it.
  12 | +
  13 | +This should allow you to build the project and run the tests, as specified in
  14 | +[Developer Notes](developer-notes.md). Please follow the instructions there.

maflcko commented at 6:48 PM on May 26, 2026:

Not sure there is any value in this now. This mostly reads like a generic "ad" for Nix and NixOS and links to a separate repo. People running Nix(os) won't need to read an "ad" for it in the Bitcoin Core docs.

Also, I don't understand why this is not in the build-unix.md docs, like all other Linux distros.

nkaretnikov commented at 7:17 PM on May 26, 2026:

mostly reads like a generic "ad"

Is it the number of links? The links are there because the wiki, manual, and download instructions are all in different places.

There are notes for other package managers already, so it's not different. It's just that you don't have to link to the apt package manager website because it's already installed on popular systems. Nix won't be installed unless you're on NixOS, but it can be used on various systems.

It's also not like we're linking to something new. Nix has a community. There are NixOS meetups. The work on Nix started in 2003. The PhD thesis was defended in 2006. The NixOS paper was published in 2010. For comparison, the Bitcoin whitepaper was published in 2008.

Not sure there is any value in this now.

I was not aware of the Bix project because it's in a separate repo. So I spent some time creating my own config when I decided to contribute. It was not a lot of time, but it was significant, and definitely longer than copy-pasting. I had to add one dependency, wait for the build to fail, add another, and repeat until I could build the project.

Sometimes building with Nix can be a pain if some tricky dependency is not packaged. Having it explicitly mentioned for people who want to use it saves time, because you know from the start that things are likely to work.

I don't understand why this is not in the build-unix.md

Nix can be used on macOS, Linux distros, and Windows (via WSL). There are dedicated sections for all three. I could have linked my notes three times from each of these, but I'm not sure that's better.

maflcko commented at 9:26 AM on May 28, 2026:

Sorry, with "ad" I mean a link to Nix. There are instructions for Ubuntu/Fedora/Alpine/etc, but none of them link to upstream. Maybe they can be skipped?

nkaretnikov commented at 4:04 PM on May 28, 2026:

Yep, I'll remove the links. The text provides enough context to understand which package manager this is about if you're not familiar, so the upstream docs and download page can be located with a web search. This way we're also not responsible if at some point they forget to renew a domain and it starts serving malware.

nkaretnikov commented at 5:05 PM on May 28, 2026:

Removed the links.

maflcko commented at 6:47 AM on May 29, 2026:

I don't understand why this is not in the build-unix.md

Nix can be used on macOS, Linux distros, and Windows (via WSL).

I know, but they are all *nix (unix-like), so build-unix.md seems like the right place.

Also, the author of bix seems to recommend

| Nix (`nix-shell -p`)       | `gcc gnumake cmake pkg-config python3 libevent boost` | `sqlite` | `capnproto` | `zeromq` | `linuxPackages.systemtap` | `qt6.qtbase qt6.qttools qt6.qtwayland qrencode` |

in #35402 (comment), which wouldn't require any external link at all.

But I am not sure what the difference is between bix and the above nix-shell -p

nkaretnikov commented at 7:39 AM on May 29, 2026:

@maflcko I'm okay with moving this to build-unix.md, because it's better than nothing, but I think it's bad for discoverability. I would not look there if I were on macOS, because there's a dedicated macOS file.

nix-shell -p is the old school way of creating a Nix environment with dependencies that are listed in the shell.nix file (no outside dependencies from the global environment).

Bix uses nix develop, which is a more recent take on nix-shell. It supports lock files, similar to pip and other package managers.

I'm okay with the idea of mentioning Nix in some way in that table, but I don't like the idea of just listing packages. Because it requires additional effort from the user to create a working environment. But it's better than nothing.

To match the format in that file, I would suggest we list the Nix packages as proposed above (in the table), but I think we should also link to Bix below.

ekzyis commented at 9:37 PM on May 26, 2026: none

If that's the preferred way of building using Nix, I think it should be linked in the documentation. AFAICT, there are no references to bix as of now. When I wanted to build Core, I followed the README at the root of the project and only found info for various OSes

Concept ACK on linking to bix. Fwiw, I also didn't know about it. I have been using uncomputable/bitcoin-nix-tools.

I suppose this comes down to "what problem are we trying to solve here".

I think a minimal nix section with a link to bix would be nice to solve the problem of not knowing about it.

maflcko commented at 9:27 AM on May 28, 2026: member

I am also thinking if the existing doc/build-unix.md could be stripped down to remove Fedora, Alpine and Arch. The only difference is the name of the package manager program and possibly the names of the packages themselves.

If we want to keep them, a simple table with the package manager name and package name should be sufficient (with or without nix).

Fixed in https://github.com/bitcoin/bitcoin/pull/35402

Remove links ae58e011f1

nkaretnikov requested review from maflcko on May 28, 2026