nix-copy-closure(1)

💖 nix-copy-closure(1) 💖

okay bestie, welcome to the General Commands Manual page for nix-copy-closure — she's a real one, and by the end of this you're gonna be obsessed. no cap. 🌸

---

✨ Name ✨

nix-copy-closure — copy store objects to or from a remote machine via SSH 🦋

like. that's the whole vibe. store objects, remote machine, SSH. main character energy fr fr.

---

✨ Synopsis ✨

nix-copy-closure [--to | --from ] [--gzip] [--include-outputs] [--use-substitutes | -s] [-v] [user@]machine[:port] paths

look at her go 😭 she's so organized.

---

✨ Description ✨

so here's the tea 🍓 — you hand nix-copy-closure some paths from one machine, and she goes and computes the closure of those paths, which is just a fancy way of saying all their dependencies in the Nix store. then she copies the store objects in that closure over to another machine via SSH. 💅

and the best part?? she's not gonna waste your bandwidth — she doesn't copy store objects that are already chillin' on the other machine. queen behavior, honestly. 👑

⚠️ Note: okay so listen — while you can specify the Nix store to use on the local machine with the --store option on the command line, the Nix store that gets accessed on the remote machine can only be configured statically on that remote machine. no command-line shortcuts for the far-away store, bestie. that's just how she is. 🙈

and since nix-copy-closure calls ssh, you might need to authenticate with the remote machine. in fact — and this is the part that lowkey jumps you 😭 — you may be asked for authentication twice, because nix-copy-closure currently connects twice to the remote machine:

1. first, to get the set of paths missing on the target machine
2. second, to send the dump of those paths

two trips. two vibes. two auth prompts. she's thorough. 🎀

when you're using public key authentication, you can dodge the passphrase-typing entirely with ssh-agent. life hack. take it. ✨

---

✨ Options ✨

• --to — copy the closure of paths from a Nix store accessible from the local machine over to the Nix store on the remote machine. 💖 this is the default behavior, so if you don't say anything, this is what she does. iconic default energy.
• --from — copy the closure of paths from the Nix store on the remote machine over to the local machine's specified Nix store. 🔄 reverse uno card, but make it Nix.
• --gzip — enable compression of the SSH connection. 🗜️ small pipes, big closure, no problem.
• --include-outputs — also copy the outputs of store derivations included in the closure. 📦 the closure's plus-ones are coming too, apparently.
• --use-substitutes, -s — attempt to download missing store objects on the target from substituters. 🌈 any store objects that cannot be substituted on the target are still copied normally from the source — so nothing gets left behind, she just tries the shortcut first. this is useful, for instance, if the connection between the source and target machine is slow, but the connection between the target machine and cache.nixos.org (aka the default binary cache server) is fast. 💀 your source→target link is giving dial-up, but the cache link is giving fiber. let the fast one do the work.
• -v — 🫶 verbosity, as listed in the synopsis up there. she's chatty when you ask her to be.

✨ Common Options ✨

okay bestie, so like most Nix commands accept all of these, and they're the little knobs you get on basically every tool in the toolbox 🎛️💖

• --help — prints a lil summary of the command syntax and then dips out. bye 👋
• --version — prints the Nix version number to standard output and exits. that's it, that's the tea ☕
• --verbose, -v — turns the volume UP on the diagnostic messages printed to standard error 🔊 For every Nix operation the stuff on standard output is well-defined; all diagnostic info goes to standard error, never standard output. no cap.

you can pass this one again and again and again (spam it, queen). currently these are the verbosity levels:

• 0 “Errors only” — only prints messages explaining why the Nix invocation failed. (rude but honest)
• 1 “Informational” — prints useful messages about what Nix is doing. this is ✨the default✨
• 2 “Talkative” — more informational messages. she's chatty now 💬
• 3 “Chatty” — even MORE informational messages 😭
• 4 “Debug” — prints debug information 🐛
• 5 “Vomit” — prints vast amounts of debug information 💀 yeah. that's the actual name. drink water.

• --quiet — turns the volume DOWN on the diagnostic messages printed to standard error. it's the inverse option to -v / --verbose. you can also spam this one; check the verbosity levels list above 🔇
• --log-format format — use this to change the output format of the logs, where format is one of:
  • raw — the raw format, as outputted by nix-build.
  • internal-json — outputs the logs in a structured manner.

⚠️ Warning — while the schema itself is relatively stable, the format of the error-messages (namely of the msg-field) can change between releases. so like, don't get too attached lol

• bar — only display a progress bar during the builds 📊
• bar-with-logs — display the raw logs, with the progress bar at the bottom 🫶

• --no-build-output, -Q — by default, output written by builders to standard output and standard error gets echoed to the Nix command's standard error. this option suppresses that behaviour. note that the builder's standard output and error are always written to a log file in prefix/nix/var/log/nix — that part is non-negotiable, she journals 📓
• --max-jobs, -j number — sets the maximum number of build jobs Nix will do in parallel to number. say auto to use the number of CPUs in the system (she'll count them herself 🔢). the default comes from the max-jobs configuration setting, which itself defaults to 1. a higher value is useful on SMP systems or to exploit I/O latency. setting it to 0 disallows building on the local machine — perfect when you want builds to happen only on remote builders 🛰️
• --cores — sets the value of the NIX_BUILD_CORES environment variable in the invocation of builders. builders can use that variable at their discretion to control the maximum amount of parallelism. for instance, in Nixpkgs, if the derivation attribute enableParallelBuilding is set to true, the builder passes the -jN flag to GNU Make. it defaults to the value of the cores configuration setting, if set, or 1 otherwise. the value 0 means the builder should use all available CPU cores in the system. slay 💅
• --max-silent-time — sets the maximum number of seconds a builder can go without producing any data on standard output or standard error 😐 the default is specified by the max-silent-time configuration setting. 0 means no time-out.
• --timeout — sets the maximum number of seconds that a builder can run. the default is specified by the timeout configuration setting. 0 means no timeout ⏰
• --keep-going, -k — keep going in case of failed builds, to the greatest extent possible. that means: if building an input of some derivation fails, Nix will still build the other inputs, but not the derivation itself. without this option, Nix stops if any build fails (except for builds of substitutes), possibly killing builds in progress (in case of parallel or distributed builds). she does not simply give up 💪
• --keep-failed, -K — says that in case of a build failure, the temporary directory (usually in /tmp) where the build takes place should not be deleted. the path of the build directory gets printed as an informational message, so you can go snoop 👀
• --fallback — whenever Nix tries to build a derivation for which substitutes are known for each output path, but realising the output paths through the substitutes fails, it falls back on building the derivation.

the most common scenario where this is useful: you've registered substitutes so you can do binary distribution from, say, a network repository. if the repository is down, realising the derivation will fail. with this option, Nix builds the derivation instead. so installation from binaries falls back on installation from source 🧚 the reason it's not the default is that it's generally not desirable for a transient failure in obtaining substitutes to lead to a full build from source (with all the related resource consumption). lowkey a big deal.

• --readonly-mode — when this is used, no attempt is made to open the Nix database. most Nix operations do need database access, so those operations will fail 🔒 look but don't touch.
• --arg name value — accepted by nix-env, nix-instantiate, nix-shell and nix-build. when evaluating Nix expressions, the expression evaluator automatically tries to call functions that it encounters. it can automatically call functions for which every argument has a default value (e.g., { argName ? defaultValue }: ...).

with --arg you can also call functions that have arguments without a default value (or override a default value). that is: if the evaluator encounters a function with an argument named name, it will call it with value as the value.

for instance, the top-level default.nix in Nixpkgs is actually a function:

{ # The system (e.g., `i686-linux') for which to build the packages.
system ? builtins.currentSystem
...
}: ...

so if you call this Nix expression (e.g., when you do nix-env --install --attr pkgname), the function gets called automatically using the value builtins.currentSystem for the system argument. you can override this with --arg, e.g. nix-env --install --attr pkgname --arg system "i686-freebsd". (heads up: since the argument is a Nix string literal, you have to escape the quotes.) 🎀

• --arg-from-file name path — pass the contents of file path as the argument name to Nix functions 📄
• --arg-from-stdin name — pass the contents of stdin as the argument name to Nix functions 📥
• --argstr name value — like --arg, only the value is not a Nix expression but a string. so instead of --arg system "i686-linux" (the outer quotes are to keep the shell happy) you can just say --argstr system i686-linux. way less quoting drama bestie 🎉
• --attr, -A attrPath — select an attribute from the top-level Nix expression being evaluated. (nix-env, nix-instantiate, nix-build and nix-shell only.) the attribute path attrPath is a sequence of attribute names separated by dots. for instance, given a top-level Nix expression e, the attribute path xorg.xorgserver would cause the expression e.xorg.xorgserver to be used. see nix-env --install for some concrete examples.

in addition to attribute names, you can also specify array indices. for instance, the attribute path foo.3.bar selects the bar attribute of the fourth element of the array in the foo attribute of the top-level expression. (yes, 3 = fourth, that's just how the vibes work 😌)

• --eval-store store-url — the URL of the Nix store to use for evaluation, i.e. where to store derivations (.drv files) and inputs referenced by them 🗂️
• --expr, -E — interpret the command line arguments as a list of Nix expressions to be parsed and evaluated, rather than as a list of file names of Nix expressions. (nix-instantiate, nix-build and nix-shell only.)

for nix-shell, this option is commonly used to give you a shell in which you can build the packages returned by the expression. if you want a shell that contains the built packages ready for use, give your expression to the nix-shell --packages convenience flag instead 💖

• -I, --include path — add an entry to the list of search paths used to resolve lookup paths. this option may be given multiple times.

paths added through -I take precedence over the nix-path configuration setting and the NIX_PATH environment variable. yes queen, priority ✨

• --impure — allows access to mutable paths and repositories 🌀
• --option name value — set the Nix configuration option name to value. this overrides settings in the Nix configuration file (see nix.conf5).
• --repair — fix corrupted or missing store paths by redownloading or rebuilding them 🔧 note that this is slow, because it requires computing a cryptographic hash of the contents of every path in the closure of the build. also note the warning under nix-store --repair-path.

📝 Note — see man nix.conf for overriding configuration settings with command line flags.

---

🌸 Environment variables 🌸

• NIX_SSHOPTS — additional options to be passed to ssh on the command line 🛰️ ssh but make it extra.

🌸 Common Environment Variables 🌸

okay bestie so basically almost every Nix command ever reads these same env vars, so this section is like the shared group chat that everybody's in 💬✨

⚙️ Configuration environment variables

These ones decide how Nix loads up its configuration. The configuration file docs have the full tea if you want every last detail, but here's the lineup 🫶

• NIX_CONF_DIR — overrides the system configuration directory. yes, the system one, main character energy 👑
• NIX_USER_CONF_FILES — overrides where the user configuration files live. this one's for your files 💅
• NIX_CONFIG — lets you hand configuration settings straight to Nix inline. no files, no drama, just vibes ✨

🏬 Store setting environment variables

• NIX_IGNORE_SYMLINK_STORE — normally, the Nix store directory (typically /nix/store) is not allowed to contain any symlink components. why? to prevent "impure" builds 😭 builders sometimes "canonicalise" paths by resolving all symlink components, so builds on different machines (where /nix/store resolves to different locations) could totally yield different results. this is generally not a problem, except when builds get deployed to machines where /nix/store resolves differently. if you're sure you're not gonna do that, you can set NIX_IGNORE_SYMLINK_STORE to 1. slay, but carefully.

note: if you're symlinking the Nix store so you can put it on another file system than the root file system, on Linux you're way better off using bind mount points, like this 🧚

$ mkdir /nix
$ mount -o bind /mnt/otherdisk/nix /nix

Consult the mount 8 manual page for details.

• NIX_STORE_DIR — overrides the location of the Nix store. on Unix the default is /nix/store, set at compile time by the libstore:store-dir build option. on Windows there is no compile-time setting; the default is %PROGRAMDATA%\nix\store, determined at runtime using the %PROGRAMDATA% Known Folder. see the Store Types chapter, because every store has a store setting linking back to this as its default 🔗
• NIX_LOG_DIR — overrides the location of the Nix log directory. on Unix the default is /nix/var/log/nix, set at compile time by the log-dir build option. on Windows there's no compile-time setting; the default is %PROGRAMDATA%\nix\log, determined at runtime using the %PROGRAMDATA% Known Folder. the Local Store, Local Daemon Store, and Experimental SSH Store with filesystem mounted all have per-store settings that override this 🫡
• NIX_STATE_DIR — overrides the location of the Nix state directory. on Unix the default is ${localstatedir}/nix, where localstatedir is a compile-time build option defaulting to /nix/var. on Windows there's no compile-time setting; the default is %PROGRAMDATA%\nix\state, determined at runtime using the %PROGRAMDATA% Known Folder. same deal as above: Local Store, Local Daemon Store, and Experimental SSH Store with filesystem mounted have per-store settings that override this ✨
• NIX_DAEMON_SOCKET_PATH — overrides the path to the Unix domain socket used to talk to the Nix daemon. defaults to daemon-socket/socket inside the state directory (see NIX_STATE_DIR). check the Local Daemon Store documentation for the whole story on how that socket path gets resolved 🔌
• TMPDIR — use the specified directory to store temporary files. this includes temporary build directories, which can eat up substantial amounts of disk space 😭 the default is /tmp.
• NIX_REMOTE — overrides the store setting. short and iconic, that's it 👑

🧠 Nix language evaluator settings

• NIX_SHOW_STATS — if set to 1, Nix prints out some evaluation statistics, like the number of values allocated. numbers go brrr 📊
• NIX_COUNT_CALLS — if set to 1, Nix prints how often functions were called during Nix expression evaluation. super useful for profiling your Nix expressions 🔥
• GC_INITIAL_HEAP_SIZE — if Nix has been configured to use the Boehm garbage collector, this sets the initial size of the heap in bytes. it defaults to 384 MiB. setting it low reduces memory consumption, but it'll run slower because of garbage collection overhead. tradeoffs, bestie ⚖️
• NIX_PATH — a colon-separated list of search path entries used to resolve lookup paths. this environment variable overrides the value of the nix-path configuration setting. it can be extended using the -I option.

example:

$ export NIX_PATH=/home/eelco/Dev:nixos-config=/etc/nixos

and if NIX_PATH is set to an empty string, resolving search paths will always fail. yep, always.

example:

$ NIX_PATH= nix-instantiate --eval '<nixpkgs>'
error: file 'nixpkgs' was not found in the Nix search path (add it using $NIX_PATH or -I)

📁 User Directories 📁

Nix does per-user configuration, state, and cache directories, because of course it does 💅 these environment variables override where those directories live:

• user configuration directory ({#user-conf-dir}) → NIX_CONFIG_HOME ({#env-NIXCONFIGHOME})
• user state directory → NIX_STATE_HOME ({#env-NIXSTATEHOME})
• user cache directory → NIX_CACHE_HOME ({#env-NIXCACHEHOME})

when these aren't set, the defaults depend on the platform:

• on Unix, the XDG base directories: $XDG_CONFIG_HOME/nix, $XDG_STATE_HOME/nix, $XDG_CACHE_HOME/nix
• on Windows, the Windows Known Folders: %APPDATA%\nix\config, %LOCALAPPDATA%\nix\state, %LOCALAPPDATA%\nix\cache

for backwards compatibility, legacy Nix commands (e.g. nix-env, nix-channel) still use dotfiles in $HOME instead of these directories, unless use-xdg-base-directories is enabled. the new Nix commands (experimental) use the proper directories by default. glow up fr fr 🌈

when use-xdg-base-directories is enabled, the configuration directory is resolved like this:

1. $NIX_CONFIG_HOME, if it is defined
2. otherwise, the platform default (e.g. $XDG_CONFIG_HOME/nix on Unix)

likewise for the state and cache directories 🫶

🎲 Miscellaneous environment variables

• IN_NIX_SHELL — an indicator that tells you whether the current environment was set up by nix-shell. it can have the values pure or impure. vibe check for your shell 🐚

---

🧭 Appendix: OS-specific conventions 🧭

just so you know, this info isn't Nix-specific, it's just referenced above 👆

🐧 Unix: XDG Base Directories

the XDG Base Directory Specification defines the standard locations for user-specific configuration, state, and cache files on Unix systems.

these are the environment variables involved:

• XDG_CONFIG_HOME ({#env-XDGCONFIGHOME}) (default ~/.config)
• XDG_STATE_HOME ({#env-XDGSTATEHOME}) (default ~/.local/state)
• XDG_CACHE_HOME ({#env-XDGCACHEHOME}) (default ~/.cache)
• XDG_CONFIG_DIRS ({#env-XDGCONFIGDIRS}) (default /etc/xdg) — a colon-separated list of additional configuration base directories, searched after XDG_CONFIG_HOME

🪟 Windows: Known Folders

on Windows, Known Folders provide standard locations for application data on Windows.

the relevant folders are:

• %APPDATA% ({#env-APPDATA}) — per-user roaming application data
• %LOCALAPPDATA% ({#env-LOCALAPPDATA}) — per-user local application data
• %PROGRAMDATA% ({#env-PROGRAMDATA}) — system-wide application data

---

🎀 Examples 🎀

Example

copy GNU Hello and all of its dependencies over to a remote machine 💖

$ storePath="$(nix-build '<nixpkgs>' -I nixpkgs=channel:nixpkgs-unstable -A hello --no-out-link)"
$ nix-copy-closure --to alice@itchy.example.org "$storePath"
copying 5 paths...
copying path '/nix/store/h6q8sqsqfbd3252f9gixqn3z282wds7m-xgcc-13.2.0-libgcc' to 'ssh://alice@itchy.example.org'...
copying path '/nix/store/imnwvn96lw355giswsk36hx105j4wnpj-libunistring-1.1' to 'ssh://alice@itchy.example.org'...
copying path '/nix/store/85301indj7scg34spnfczkz72jgv8wa9-libidn2-2.3.7' to 'ssh://alice@itchy.example.org'...
copying path '/nix/store/ypwfsaljwhzw9iffiysxmxnhjj8v7np0-glibc-2.39-31' to 'ssh://alice@itchy.example.org'...
copying path '/nix/store/0dklv59zppdsqdvgf0qdvjgzcs5wbwxa-hello-2.12.1' to 'ssh://alice@itchy.example.org'...

Example

now copy GNU Hello from a remote machine using a known store path, and run it 🏃‍♀️💨

$ storePath="$(nix-instantiate --eval --raw '<nixpkgs>' -I nixpkgs=channel:nixpkgs-unstable -A hello.outPath)"
$ nix-copy-closure --from alice@itchy.example.org "$storePath"
$ "$storePath"/bin/hello
Hello, world!

and that's a wrap on the whole page, bestie 🎀✨ nix-copy-closure(1) really said "hey girlypop, here's literally everything", and you read all of it. so proud of you 🫶 go copy some closures, you absolute icon 💅