···

       
1
       
1
       
 
       
# pkgs.mkBinaryCache {#sec-pkgs-binary-cache}

     

       
2
       
2
       
 
       


     

       
3
       
3
       
-
       
`pkgs.mkBinaryCache` is a function for creating Nix flat-file binary caches. Such a cache exists as a directory on disk, and can be used as a Nix substituter by passing `--substituter file:///path/to/cache` to Nix commands.

     

       
3
       
3
       
+
       
`pkgs.mkBinaryCache` is a function for creating Nix flat-file binary caches.

     

       
4
       
4
       
+
       
Such a cache exists as a directory on disk, and can be used as a Nix substituter by passing `--substituter file:///path/to/cache` to Nix commands.

     

       
4
       
5
       
 
       


     

       
5
       
5
       
-
       
Nix packages are most commonly shared between machines using [HTTP, SSH, or S3](https://nixos.org/manual/nix/stable/package-management/sharing-packages.html), but a flat-file binary cache can still be useful in some situations. For example, you can copy it directly to another machine, or make it available on a network file system. It can also be a convenient way to make some Nix packages available inside a container via bind-mounting.

     

       
6
       
6
       
+
       
Nix packages are most commonly shared between machines using [HTTP, SSH, or S3](https://nixos.org/manual/nix/stable/package-management/sharing-packages.html), but a flat-file binary cache can still be useful in some situations.

     

       
7
       
7
       
+
       
For example, you can copy it directly to another machine, or make it available on a network file system.

     

       
8
       
8
       
+
       
It can also be a convenient way to make some Nix packages available inside a container via bind-mounting.

     

       
6
       
9
       
 
       


     

       
7
       
7
       
-
       
Note that this function is meant for advanced use-cases. The more idiomatic way to work with flat-file binary caches is via the [nix-copy-closure](https://nixos.org/manual/nix/stable/command-ref/nix-copy-closure.html) command. You may also want to consider [dockerTools](#sec-pkgs-dockerTools) for your containerization needs.

     

       
10
       
10
       
+
       
`mkBinaryCache` expects an argument with the `rootPaths` attribute.

     

       
11
       
11
       
+
       
`rootPaths` must be a list of derivations.

     

       
12
       
12
       
+
       
The transitive closure of these derivations' outputs will be copied into the cache.

     

       
8
       
13
       
 
       


     

       
9
       
9
       
-
       
## Example {#sec-pkgs-binary-cache-example}

     

       
14
       
14
       
+
       
::: {.note}

     

       
15
       
15
       
+
       
This function is meant for advanced use cases.

     

       
16
       
16
       
+
       
The more idiomatic way to work with flat-file binary caches is via the [nix-copy-closure](https://nixos.org/manual/nix/stable/command-ref/nix-copy-closure.html) command.

     

       
17
       
17
       
+
       
You may also want to consider [dockerTools](#sec-pkgs-dockerTools) for your containerization needs.

     

       
18
       
18
       
+
       
:::

     

       
19
       
19
       
+
       


     

       
20
       
20
       
+
       
[]{#sec-pkgs-binary-cache-example}

     

       
21
       
21
       
+
       
:::{.example #ex-mkbinarycache-copying-package-closure}

     

       
22
       
22
       
+
       


     

       
23
       
23
       
+
       
# Copying a package and its closure to another machine with `mkBinaryCache`

     

       
10
       
24
       
 
       


     

       
11
       
25
       
 
       
The following derivation will construct a flat-file binary cache containing the closure of `hello`.

     

       
12
       
26
       
 
       


     

       
13
       
27
       
 
       
```nix

     

       
28
       
28
       
+
       
{ mkBinaryCache, hello }:

     

       
14
       
29
       
 
       
mkBinaryCache {

     

       
15
       
30
       
 
       
  rootPaths = [hello];

     

       
16
       
31
       
 
       
}

     

       
17
       
32
       
 
       
```

     

       
18
       
33
       
 
       


     

       
19
       
19
       
-
       
- `rootPaths` specifies a list of root derivations. The transitive closure of these derivations' outputs will be copied into the cache.

     

       
20
       
20
       
-
       


     

       
21
       
21
       
-
       
Here's an example of building and using the cache.

     

       
22
       
22
       
-
       


     

       
23
       
23
       
-
       
Build the cache on one machine, `host1`:

     

       
34
       
34
       
+
       
Build the cache on a machine.

     

       
35
       
35
       
+
       
Note that the command still builds the exact nix package above, but adds some boilerplate to build it directly from an expression.

     

       
24
       
36
       
 
       


     

       
25
       
37
       
 
       
```shellSession

     

       
26
       
26
       
-
       
nix-build -E 'with import <nixpkgs> {}; mkBinaryCache { rootPaths = [hello]; }'

     

       
38
       
38
       
+
       
$ nix-build -E 'let pkgs = import <nixpkgs> {}; in pkgs.callPackage ({ mkBinaryCache, hello }: mkBinaryCache { rootPaths = [hello]; }) {}'

     

       
39
       
39
       
+
       
/nix/store/azf7xay5xxdnia4h9fyjiv59wsjdxl0g-binary-cache

     

       
27
       
40
       
 
       
```

     

       
28
       
41
       
 
       


     

       
42
       
42
       
+
       
Copy the resulting directory to another machine, which we'll call `host2`:

     

       
43
       
43
       
+
       


     

       
29
       
44
       
 
       
```shellSession

     

       
30
       
30
       
-
       
/nix/store/cc0562q828rnjqjyfj23d5q162gb424g-binary-cache

     

       
45
       
45
       
+
       
$ scp result host2:/tmp/hello-cache

     

       
31
       
46
       
 
       
```

     

       
32
       
47
       
 
       


     

       
33
       
33
       
-
       
Copy the resulting directory to the other machine, `host2`:

     

       
48
       
48
       
+
       
At this point, the cache can be used as a substituter when building derivations on `host2`:

     

       
34
       
49
       
 
       


     

       
35
       
50
       
 
       
```shellSession

     

       
36
       
36
       
-
       
scp result host2:/tmp/hello-cache

     

       
37
       
37
       
-
       
```

     

       
38
       
38
       
-
       


     

       
39
       
39
       
-
       
Substitute the derivation using the flat-file binary cache on the other machine, `host2`:

     

       
40
       
40
       
-
       
```shellSession

     

       
41
       
41
       
-
       
nix-build -A hello '<nixpkgs>' \

     

       
51
       
51
       
+
       
$ nix-build -A hello '<nixpkgs>' \

     

       
42
       
52
       
 
       
  --option require-sigs false \

     

       
43
       
53
       
 
       
  --option trusted-substituters file:///tmp/hello-cache \

     

       
44
       
54
       
 
       
  --option substituters file:///tmp/hello-cache

     

       
55
       
55
       
+
       
/nix/store/zhl06z4lrfrkw5rp0hnjjfrgsclzvxpm-hello-2.12.1

     

       
45
       
56
       
 
       
```

     

       
46
       
57
       
 
       


     

       
47
       
47
       
-
       
```shellSession

     

       
48
       
48
       
-
       
/nix/store/gl5a41azbpsadfkfmbilh9yk40dh5dl0-hello-2.12.1

     

       
49
       
49
       
-
       
```

     

       
58
       
58
       
+
       
:::