(reading-nix-repl)=
Prerequisites:
- Nix Language Basics
- A recent Nix installation (2.10 or newer)
# Tour of the Nix REPL
Nix provides a REPL for interactively exploring Nix expressions (including, but not limited, to Nix packages).
In the simplest case, you can use the Nix REPL as a basic calculator:
```bash
$ nix repl
```
```nix
nix-repl> 2 + 2
4
```
You can define variables and use them within the REPL:
```
nix-repl> greeting = "Hello"
nix-repl> "${greeting}, world!"
"Hello, world!"
```
It can be used to look up documentation of built-in functions:
```nix
nix-repl> :doc builtins.concatMap
Synopsis: builtins.concatMap f list
This function is equivalent to builtins.concatLists (map f list) but is more efficient.
```
… but in practice you will more likely use the REPL to explore and debug Nix packages.
For example, you can load all of Nixpkgs into the REPL like this:
```bash
$ nix repl -f '<nixpkgs>'
```
Here `<nixpkgs>` refers to the `nixpkgs` entry in `NIX_PATH`. You can also insert the path to a local nixpkgs checkout to inspect a specific version of nixpkgs that is not currently in active use on your system.
:::{note}
Nix Versions 2.9 or older didn't support the `-f`/`--file` flag.
:::
… and you can build a sample package (like the GNU `hello` package) using the `:b` command:
```nix
nix-repl> :b hello
This derivation produced the following outputs:
out -> /nix/store/akjp4x41jjx5hzgzrschwqzr8qfsdpys-hello-2.12.1
```
… but you can also explore packages without building them, too, since they are pure expressions. In fact, every Nix package is actually an attribute set that you can inspect within the REPL without having to build the package.
Our `hello` package has several useful attributes we can inspect, like these:
```nix
nix-repl> hello.pname # The package name
"hello"
nix-repl> hello.version # The package version
"2.12.1"
nix-repl> hello.meta.license.fullName # The license
"GNU General Public License v3.0 or later"
```
… and like many other language REPLs, you can browse the available attributes using auto-completion:
```nix
nix-repl> hello.<TAB>
hello.__darwinAllowLocalNetworking hello.mesonFlags
hello.__ignoreNulls hello.meta
hello.__impureHostDeps hello.name
hello.__propagatedImpureHostDeps hello.nativeBuildInputs
hello.__propagatedSandboxProfile hello.out
hello.__sandboxProfile hello.outPath
…
nix-repl> hello.meta.<TAB>
hello.meta.available hello.meta.maintainers
hello.meta.broken hello.meta.name
hello.meta.changelog hello.meta.outputsToInstall
hello.meta.description hello.meta.platforms
hello.meta.homepage hello.meta.position
hello.meta.insecure hello.meta.unfree
hello.meta.license hello.meta.unsupported
hello.meta.longDescription
```
TODO:
- [x] use it as a calculator
- [ ] strictness
- [ ] building derivations
- [ ] variables
- [ ] specific examples from Nixpkgs
- [ ] specific examples from NixOS (e.g. inspect a NixOS system)
- [ ] reloading files
- [ ] documentation for builtins
- [ ] loading existing files
- [ ] autocompletion
- [ ] check to see if we missed any `:` commands
- [ ] especially `:?`