Styjun

For example in the following (which I assume is a nix expression):

(import <nixpkgs> ).haskellPackages.ghcWithPackages (hpkgs: with hpkgs; [
 lens
 aeson
 turtle
])

What does <nixpkgs> reference? I also see it used in other contexts for example:

nix-shell '<nixpkgs>' -A linuxPackages.kernel

<nixpkgs> is a Nix expression that is evaluated by looking at the Nix search path in the NIX_PATH environment variable and/or -I option.

It is described in more detail in the Nix manual.

Note that the Nix search path is impractical in many situations. You can only pass it from the outside, and it easily creates impurity. In my experience, problems are better solved with explicit argument passing or the functions relating to fix-points like callPackage and the overlay system.

As an example, NixOS has only one extra search path parameter, and it is only read once in nixos/default.nix if no explicit configuration is given. This way, you have the flexibility to provide your own configuration, which is why you (nix-build) and hydra can confidently build the NixOS VM tests, bootable images, docker images, etc.

One can evaluate the value using nix repl:

 nix repl
Welcome to Nix version 2.1.3. Type :? for help.

nix-repl> <nixpkgs>
/nix/var/nix/profiles/per-user/root/channels/nixos

From the Nix manual, 15.1. Values, section "Simple Values":

Paths can also be specified between angle brackets, e.g. .
This means that the directories listed in the environment variable
NIX_PATH will be searched for the given file or directory name.

From the NixOS manual, Chapter 18. Common Environment Variables, section NIX_PATH:

A colon-separated list of directories used to look up Nix expressions
enclosed in angle brackets (i.e., ). For instance, the value

/home/eelco/Dev:/etc/nixos

will cause Nix to look for paths relative to /home/eelco/Dev and
/etc/nixos, in that order. It is also possible to match paths
against a prefix. For example, the value

nixpkgs=/home/eelco/Dev/nixpkgs-branch:/etc/nixos

will cause Nix to search for <nixpkgs/path> in
/home/eelco/Dev/nixpkgs-branch/path and /etc/nixos/nixpkgs/path.

If a path in the Nix search path starts with http:// or https://,
it is interpreted as the URL of a tarball that will be downloaded and
unpacked to a temporary location. The tarball must consist of a single
top-level directory. For example, setting NIX_PATH to

nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/nixos-15.09.tar.gz

tells Nix to download the latest revision in the Nixpkgs/NixOS 15.09
channel.

A following shorthand can be used to refer to the official channels:

nixpkgs=channel:nixos-15.09

The search path can be extended using the -I option, which takes
precedence over NIX_PATH.

Examples

1. with import <nixpkgs> ; /* rest of the expression */

In my case, <nixpkgs> is /nix/var/nix/profiles/per-user/root/channels/nixos:

$ echo $NIX_PATH 
# VVVVVVV
/home/a_user/.nix-defexpr/channels:nixpkgs=/nix/var/nix/profiles/per-user/root/channels/nixos:nixos-config=/etc/nixos/configuration.nix:/nix/var/nix/profiles/per-user/root/channels
# ^^^^^^^

Because <nixpkgs> evaluates to "a directory, the file default.nix in that directory is loaded" by import. (Nix manual, 15.4.1. Advanced Attributes, section import path, builtins.import path)

$ ll /nix/var/nix/profiles/per-user/root/channels/nixos
lrwxrwxrwx 1 root root 80 Dec 31 1969 /nix/var/nix/profiles/per-user/root/channels/nixos -> /nix/store/ywlfq2ns4
a3fzb2ap74lvahmrg1p0lmk-nixos-19.03.172231.7b36963e7a7/nixos/

$ ll $(readlink -f /nix/var/nix/profiles/per-user/root/channels/nixos)
total 3308
dr-xr-xr-x 8 root root 4096 Dec 31 1969 ./
dr-xr-xr-x 4 root root 4096 Dec 31 1969 ../
# (...)
dr-xr-xr-x 7 root root 4096 Dec 31 1969 nixos/
dr-xr-xr-x 17 root root 4096 Dec 31 1969 pkgs/
-r--r--r-- 1 root root 1097 Dec 31 1969 COPYING
-r--r--r-- 1 root root 968 Dec 31 ---> default.nix <---
# (...)

If my understanding is correct, after the import the provided Nix expression is evaluated with an empty attribute set (). The result is an attribute list, and the with expression will include all its containing attributes in the local lexical scope.

2. nix repl '<nixpkgs/nixos>'

Example taken from the NixOS manual, 5.3. Modularity, showing the active NixOS configuration settings in the repl.

Because of the <nixpkgs/path> convention, where path equals nixos, the angle expression will evaluate to /nix/var/nix/profiles/per-user/root/channels/nixos/nixos. The above ll output also shows a nixos folder above default.nix, and inside there is indeed another default.nix that will get evaluated by nix repl:

$ ll $(readlink -f /nix/var/nix/profiles/per-user/root/channels/nixos/nixos)
total 72
dr-xr-xr-x 7 root root 4096 Dec 31 1969 ./
dr-xr-xr-x 8 root root 4096 Dec 31 1969 ../
-r--r--r-- 1 root root 886 Dec 31 ---> default.nix <---
-r--r--r-- 1 root root 197 Dec 31 1969 README
-r--r--r-- 1 root root 6074 Dec 31 1969 release-combined.nix
-r--r--r-- 1 root root 9251 Dec 31 1969 release.nix
-r--r--r-- 1 root root 2038 Dec 31 1969 release-small.nix

Miscellaneous

• 
  Issue #338 is still open to improve the Nix manual, documenting the angle syntax in their own section.


• 
  Nix Pills sections (e.g., 15.5. Conclusion and Chapter 16. Nixpkgs Parameters) consistently call the angle syntax "angular brackets" syntax.


• 
  In his answer, Robert Hensing warns against using <nixpkgs> everywhere, and an issue #1161 is still open on just that topic. (Excerpt: "We have an unofficial guideline that nobody should use angle brackets in nixpkgs, but why not make it into a hard requirement?")