Skip to content

Getting Started

Welcome! It's great to see that you're interested in Nix and also in Ethereum.nix. These installation instructions are intended to have a basic installation of Nix on your system ready to be used alongside Ethereum.nix.

Of course, if you're a seasoned Nix user, these installation instructions can be safely skipped (as you probably know what you're doing!).

What is exactly Nix?

Some people might need clarification on what exactly is Nix. To clarify:

We recommend you have a look at the following sources to get yourself familiar with the Nix ecosystem and mechanics first before starting with Ethereum.nix:

  • Zero to Nix: A well-written guide with insightful information about using Nix and several important concepts.
  • Nix Reference Manual: This is a more comprenhensive guide (and also more notoriosly difficult) about Nix.

Installation

Nix, the package manager, can be installed quite easily using the official installation script. We have left the installation instructions here for your convenience1. Still, we recommend looking at the official source should you have more questions or want to customize the installation experience.

On non-Nix systems (Linux, MacOS, Windows WSL2, Docker)

For some systems, there are two installation methods:

Which type of installation should you choose? Multi-user or Single user?

This depends on your requirements, but here is a short list of reasons why it's recommended the multi-user installation:

Pros:

  • Better build isolation (and that is what Nix is all about).
  • Better security (a build can not write somewhere in your home).
  • Sharing builds between users.

Cons:

  • Requires root to run the daemon.
  • More involved installation (creation of nixbld* users, installing a systemd unit, ...).
  • Harder to uninstall.

To run the installer:

1
sh <(curl -L https://nixos.org/nix/install) --daemon

Info

We recommend the multi-user install if you are on Linux running systemd, with SELinux disabled and you can authenticate with sudo.

1
sh <(curl -L https://nixos.org/nix/install) --no-daemon

Info

Above command will perform a single-user installation of Nix, meaning that /nix is owned by the invoking user. You should run this under your usual user account, not as root. The script will invoke sudo to create /nix if it doesn’t already exist.

1
sh <(curl -L https://nixos.org/nix/install) --daemon

1
sh <(curl -L https://nixos.org/nix/install) --daemon

Info

WSL versions 0.67.6 and above have systemd support. Follow Microsoft's systemd guide to configure it, and then install Nix using

1
sh <(curl -L https://nixos.org/nix/install) --no-daemon

Start a Docker shell with Nix:

1
docker run -it nixos/nix

Or start a Docker shell with Nix exposing a workdir directory:

1
2
mkdir workdir
docker run -it -v $(pwd)/workdir:/workdir nixos/nix

Open a new terminal session, and the nix executable should be in your $PATH. To verify that:

1
nix --version

This should print the version information for Nix.

On NixOS

If you're running NixOS, you don't need to install Nix, as it's already included!

Enable Flakes Support

Make sure Nix Flakes functionality is enabled to ease your operations when using Ethereum.nix.

Aren't Nix Flakes experimental?

Nix flakes are still in the experimental stage within Nix, and there's no defined timeline for their official launch. While we don't expect significant changes to the user interface for flakes during the experimental phase, there could still be some minor changes.

We believe that enabling Flakes is the best form of learning Nix for those new to the ecosystem.

On non-Nix systems (Linux, MacOS, Windows WSL2, Docker)

Edit (or create) either ~/.config/nix/nix.conf or /etc/nix/nix.conf and add the following entry:

1
experimental-features = nix-command flakes

If the Nix installation is in multi-user mode, don’t forget to restart the nix-daemon.

To verify that Nix flakes are enabled just type the following on the terminal:

1
nix show-config | grep flakes

It should display what we already wrote on the config file:

1
experimental-features = flakes nix-command

On NixOS

To do so, edit your configuration.nix and add the following:

1
2
3
{ pkgs, ... }: {
  nix.settings.experimental-features = [ "nix-command" "flakes" ];
}

And rebuild your system closure! That's it!

Add Ethereum.nix to your Flake registry

When dealing with Ethereum.nix, we can use of flakes registries. Flake registries are a convenience feature that allows you to refer to flakes using symbolic identifiers such as nixpkgs, rather than full URLs such as git://github.com/NixOS/nixpkgs. You can use these identifiers on the command line (e.g. when you do nix run nixpkgs#hello) or in flake input specifications in flake.nix files.

If you're curious, you can list all registries that are available in your system with the following command:

1
nix registry list

We do recommend adding Ethereum.nix to your flake registry. To do so:

1
nix registry add enix github:nix-community/ethereum.nix # (1)!

You can verify that this works by just typing the following:

1
nix run enix#geth -- --version

After a while (the first invocation, the command will take a little bit), the current version of geth should appear!

  1. You can choose another alias instead of enix. We named it enix because it's short and sweet!

  1. Thanks to the Nix/NixOS documentation team. ↩