guix archive command allows users to export files
from the store into a single archive, and to later import them on
a machine that runs Guix.
In particular, it allows store files to be transferred from one machine
to the store on another machine.
Note: If you’re looking for a way to produce archives in a format suitable for tools other than Guix, see Invoking guix pack.
To export store files as an archive to standard output, run:
guix archive --export options specifications...
specifications may be either store file names or package
specifications, as for
guix package (see Invoking guix package). For instance, the following command creates an archive
gui output of the
git package and the main
guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
If the specified packages are not built yet,
automatically builds them. The build process may be controlled with the
common build options (see Common Build Options).
To transfer the
emacs package to a machine connected over SSH,
one would run:
guix archive --export -r emacs | ssh the-machine guix archive --import
Similarly, a complete user profile may be transferred from one machine to another like this:
guix archive --export -r $(readlink -f ~/.guix-profile) | \ ssh the-machine guix archive --import
However, note that, in both examples, all of
emacs and the
profile as well as all of their dependencies are transferred (due to
-r), regardless of what is already available in the store on the
target machine. The
--missing option can help figure out which
items are missing from the target store. The
command simplifies and optimizes this whole process, so this is probably
what you should use in this case (see Invoking guix copy).
Archives are stored in the “normalized archive” or “nar” format, which is comparable in spirit to ‘tar’, but with differences that make it more appropriate for our purposes. First, rather than recording all Unix metadata for each file, the nar format only mentions the file type (regular, directory, or symbolic link); Unix permissions and owner/group are dismissed. Second, the order in which directory entries are stored always follows the order of file names according to the C locale collation order. This makes archive production fully deterministic.
When exporting, the daemon digitally signs the contents of the archive, and that digital signature is appended. When importing, the daemon verifies the signature and rejects the import in case of an invalid signature or if the signing key is not authorized.
The main options are:
Export the specified store files or packages (see below.) Write the resulting archive to the standard output.
Dependencies are not included in the output, unless
--recursive is passed.
When combined with
--export, this instructs
archive to include dependencies of the given items in the archive.
Thus, the resulting archive is self-contained: it contains the closure
of the exported store items.
Read an archive from the standard input, and import the files listed
therein into the store. Abort if the archive has an invalid digital
signature, or if it is signed by a public key not among the authorized
Read a list of store file names from the standard input, one per line, and write on the standard output the subset of these files missing from the store.
Generate a new key pair for the daemon. This is a prerequisite before
archives can be exported with
--export. Note that this operation
usually takes time, because it needs to gather enough entropy to
generate the key pair.
The generated key pair is typically stored under /etc/guix, in
signing-key.pub (public key) and signing-key.sec (private
key, which must be kept secret.) When parameters is omitted,
an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt
versions before 1.6.0, it is a 4096-bit RSA key.
Alternatively, parameters can specify
genkey parameters suitable for Libgcrypt (see
gcry_pk_genkey in The
Libgcrypt Reference Manual).
Authorize imports signed by the public key passed on standard input. The public key must be in “s-expression advanced format”—i.e., the same format as the signing-key.pub file.
The list of authorized keys is kept in the human-editable file /etc/guix/acl. The file contains “advanced-format s-expressions” and is structured as an access-control list in the Simple Public-Key Infrastructure (SPKI).
Read a single-item archive as served by substitute servers (see Substitutes) and extract it to directory. This is a low-level operation needed in only very narrow use cases; see below.
For example, the following command extracts the substitute for Emacs
ci.guix.gnu.org to /tmp/emacs:
$ wget -O - \ https://ci.guix.gnu.org/nar/…-emacs-24.5 \ | bunzip2 | guix archive -x /tmp/emacs
Single-item archives are different from multiple-item archives produced
guix archive --export; they contain a single store item,
and they do not embed a signature. Thus this operation does
no signature verification and its output should be considered
The primary purpose of this operation is to facilitate inspection of archive contents coming from possibly untrusted substitute servers.
Read a single-item archive as served by substitute servers (see Substitutes) and print the list of files it contains, as in this example:
$ wget -O - \ https://ci.guix.gnu.org/nar/lzip/…-emacs-26.3 \ | lzip -d | guix archive -t