.\" -*- mode: troff; coding: utf-8 -*-
.TH "nix-prefetch-url" "1" ""
.SH
Name
.LP
\f(CRnix-prefetch-url\fR - copy a file from a URL into the store and print its hash
.SH
Synopsis
.LP
\f(CRnix-prefetch-url\fR \fIurl\fR [\fIhash\fR]
[\f(CR--type\fR \fIhashAlgo\fR]
[\f(CR--print-path\fR]
[\f(CR--unpack\fR]
[\f(CR--name\fR \fIname\fR]
.SH
Description
.LP
The command \f(CRnix-prefetch-url\fR downloads the file referenced by the URL
\fIurl\fR, prints its cryptographic hash, and copies it into the Nix store.
The file name in the store is \f(CRhash-baseName\fR, where \fIbaseName\fR is
everything following the final slash in \fIurl\fR.
.PP
This command is just a convenience for Nix expression writers. Often a
Nix expression fetches some source distribution from the network using
the \f(CRfetchurl\fR expression contained in Nixpkgs. However, \f(CRfetchurl\fR
requires a cryptographic hash. If you don\(cqt know the hash, you would
have to download the file first, and then \f(CRfetchurl\fR would download it
again when you build your Nix expression. Since \f(CRfetchurl\fR uses the same
name for the downloaded file as \f(CRnix-prefetch-url\fR, the redundant
download can be avoided.
.PP
If \fIhash\fR is specified, then a download is not performed if the Nix
store already contains a file with the same hash and base name.
Otherwise, the file is downloaded, and an error is signaled if the
actual hash of the file does not match the specified hash.
.PP
This command prints the hash on standard output.
The hash is printed using base-32 unless \f(CR--type md5\fR is specified,
in which case it\(cqs printed using base-16.
Additionally, if the option \f(CR--print-path\fR is used,
the path of the downloaded file in the Nix store is also printed.
.SH
Options
.IP "\(bu" 3
\f(CR--type\fR \fIhashAlgo\fR
.br
Use the specified cryptographic hash algorithm,
which can be one of \f(CRmd5\fR, \f(CRsha1\fR, \f(CRsha256\fR, and \f(CRsha512\fR.
The default is \f(CRsha256\fR.
.IP "\(bu" 3
\f(CR--print-path\fR
.br
Print the store path of the downloaded file on standard output.
.IP "\(bu" 3
\f(CR--unpack\fR
.br
Unpack the archive (which must be a tarball or zip file) and add the
result to the Nix store. The resulting hash can be used with
functions such as Nixpkgs’s \f(CRfetchzip\fR or \f(CRfetchFromGitHub\fR.
.IP "\(bu" 3
\f(CR--executable\fR
.br
Set the executable bit on the downloaded file.
.IP "\(bu" 3
\f(CR--name\fR \fIname\fR
.br
Override the name of the file in the Nix store. By default, this is
\f(CRhash-basename\fR, where \fIbasename\fR is the last component of \fIurl\fR.
Overriding the name is necessary when \fIbasename\fR contains characters
that are not allowed in Nix store paths.
.SH
Examples
.LP
.EX
$ nix-prefetch-url ftp://ftp.gnu.org/pub/gnu/hello/hello-2.10.tar.gz
0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i
.EE
.LP
.EX
$ nix-prefetch-url --print-path mirror://gnu/hello/hello-2.10.tar.gz
0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i
/nix/store/3x7dwzq014bblazs7kq20p9hyzz0qh8g-hello-2.10.tar.gz
.EE
.LP
.EX
$ nix-prefetch-url --unpack --print-path https://github.com/NixOS/patchelf/archive/0.8.tar.gz
079agjlv0hrv7fxnx9ngipx14gyncbkllxrp9cccnh3a50fxcmy7
/nix/store/19zrmhm3m40xxaw81c8cqm6aljgrnwj2-0.8.tar.gz
.EE