nix-super/doc/manual/src/command-ref/nix-prefetch-url.md

# Name

`nix-prefetch-url` - copy a file from a URL into the store and print its hash

# Synopsis

`nix-prefetch-url` *url* [*hash*]
  [`--type` *hashAlgo*]
  [`--print-path`]
  [`--unpack`]
  [`--name` *name*]

# Description

The command `nix-prefetch-url` downloads the file referenced by the URL
*url*, prints its cryptographic hash, and copies it into the Nix store.
The file name in the store is `hash-baseName`, where *baseName* is
everything following the final slash in *url*.

This command is just a convenience for Nix expression writers. Often a
Nix expression fetches some source distribution from the network using
the `fetchurl` expression contained in Nixpkgs. However, `fetchurl`
requires a cryptographic hash. If you don't know the hash, you would
have to download the file first, and then `fetchurl` would download it
again when you build your Nix expression. Since `fetchurl` uses the same
name for the downloaded file as `nix-prefetch-url`, the redundant
download can be avoided.

If *hash* 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.

This command prints the hash on standard output. Additionally, if the
option `--print-path` is used, the path of the downloaded file in the
Nix store is also printed.

# Options

  - `--type` *hashAlgo*\
    Use the specified cryptographic hash algorithm, which can be one of
    `md5`, `sha1`, `sha256`, and `sha512`.

  - `--print-path`\
    Print the store path of the downloaded file on standard output.

  - `--unpack`\
    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 `fetchzip` or `fetchFromGitHub`.

  - `--executable`\
    Set the executable bit on the downloaded file.

  - `--name` *name*\
    Override the name of the file in the Nix store. By default, this is
    `hash-basename`, where *basename* is the last component of *url*.
    Overriding the name is necessary when *basename* contains characters
    that are not allowed in Nix store paths.

# Examples

```console
$ nix-prefetch-url ftp://ftp.gnu.org/pub/gnu/hello/hello-2.10.tar.gz
0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i
```

```console
$ nix-prefetch-url --print-path mirror://gnu/hello/hello-2.10.tar.gz
0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i
/nix/store/3x7dwzq014bblazs7kq20p9hyzz0qh8g-hello-2.10.tar.gz
```

```console
$ nix-prefetch-url --unpack --print-path https://github.com/NixOS/patchelf/archive/0.8.tar.gz
079agjlv0hrv7fxnx9ngipx14gyncbkllxrp9cccnh3a50fxcmy7
/nix/store/19zrmhm3m40xxaw81c8cqm6aljgrnwj2-0.8.tar.gz
```
-												Clean up the manpages

											
										
										
											2020-07-24 13:56:19 +03:00
+								# Name
-												Convert commands

											
										
										
											2020-07-23 13:58:42 +03:00
-												Clean up the manpages

											
										
										
											2020-07-24 13:56:19 +03:00
+								`nix-prefetch-url` - copy a file from a URL into the store and print its hash
-												Convert commands

											
										
										
											2020-07-23 13:58:42 +03:00
-												Clean up the manpages

											
										
										
											2020-07-24 13:56:19 +03:00
+								# Synopsis
-												Convert commands

											
										
										
											2020-07-23 13:58:42 +03:00
-												Clean up the manpages

											
										
										
											2020-07-24 13:56:19 +03:00
+								`nix-prefetch-url` *url* [*hash*]
 								  [`--type` *hashAlgo*]
 								  [`--print-path`]
 								  [`--unpack`]
 								  [`--name` *name*]
-												Convert commands

											
										
										
											2020-07-23 13:58:42 +03:00
 								# Description
 								The command `nix-prefetch-url` downloads the file referenced by the URL
-												<replaceable> -> <emphasis>

Pandoc doesn't know <replaceable> so let's force it to be rendered as
italics.

											
										
										
											2020-07-23 15:28:05 +03:00
+								*url*, prints its cryptographic hash, and copies it into the Nix store.
 								The file name in the store is `hash-baseName`, where *baseName* is
 								everything following the final slash in *url*.
-												Convert commands

											
										
										
											2020-07-23 13:58:42 +03:00
 								This command is just a convenience for Nix expression writers. Often a
 								Nix expression fetches some source distribution from the network using
 								the `fetchurl` expression contained in Nixpkgs. However, `fetchurl`
 								requires a cryptographic hash. If you don't know the hash, you would
 								have to download the file first, and then `fetchurl` would download it
 								again when you build your Nix expression. Since `fetchurl` uses the same
 								name for the downloaded file as `nix-prefetch-url`, the redundant
 								download can be avoided.
-												<replaceable> -> <emphasis>

Pandoc doesn't know <replaceable> so let's force it to be rendered as
italics.

											
										
										
											2020-07-23 15:28:05 +03:00
+								If *hash* 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.
-												Convert commands

											
										
										
											2020-07-23 13:58:42 +03:00
 								This command prints the hash on standard output. Additionally, if the
 								option `--print-path` is used, the path of the downloaded file in the
 								Nix store is also printed.
 								# Options
-												Replace the trailing markdown spaces by a backslash

They are equivalent according to
<https://spec.commonmark.org/0.29/#hard-line-breaks>,
and the trailing spaces tend to be a pain (because the make git
complain, editors tend to want to remove them − the `.editorconfig`
actually specifies that − etc..).

											
										
										
											2021-04-23 15:30:42 +03:00
+								  - `--type` *hashAlgo*\
-												Convert commands

											
										
										
											2020-07-23 13:58:42 +03:00
+								    Use the specified cryptographic hash algorithm, which can be one of
-												Add sha512 to hashAlgo listings in manpages (#4186)


											
										
										
											2020-10-26 00:16:53 +02:00
+								    `md5`, `sha1`, `sha256`, and `sha512`.
-												Convert commands

											
										
										
											2020-07-23 13:58:42 +03:00
-												Replace the trailing markdown spaces by a backslash

They are equivalent according to
<https://spec.commonmark.org/0.29/#hard-line-breaks>,
and the trailing spaces tend to be a pain (because the make git
complain, editors tend to want to remove them − the `.editorconfig`
actually specifies that − etc..).

											
										
										
											2021-04-23 15:30:42 +03:00
+								  - `--print-path`\
-												Convert commands

											
										
										
											2020-07-23 13:58:42 +03:00
+								    Print the store path of the downloaded file on standard output.
-												Replace the trailing markdown spaces by a backslash

They are equivalent according to
<https://spec.commonmark.org/0.29/#hard-line-breaks>,
and the trailing spaces tend to be a pain (because the make git
complain, editors tend to want to remove them − the `.editorconfig`
actually specifies that − etc..).

											
										
										
											2021-04-23 15:30:42 +03:00
+								  - `--unpack`\
-												Convert commands

											
										
										
											2020-07-23 13:58:42 +03:00
+								    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 `fetchzip` or `fetchFromGitHub`.
-												Replace the trailing markdown spaces by a backslash

They are equivalent according to
<https://spec.commonmark.org/0.29/#hard-line-breaks>,
and the trailing spaces tend to be a pain (because the make git
complain, editors tend to want to remove them − the `.editorconfig`
actually specifies that − etc..).

											
										
										
											2021-04-23 15:30:42 +03:00
+								  - `--executable`\
-												nix-prefetch-url: Add --executable flag

pkgs.fetchurl supports an executable argument, which is especially nice
when downloading a large executable. This patch adds the same option to
nix-prefetch-url.

I have tested this to work on the simple case of prefetching a little
executable:

1. nix-prefetch-url --executable https://my/little/script
2. Paste the hash into a pkgs.fetchurl-based package, script-pkg.nix
3. Delete the output from the store to avoid any misidentified artifacts
4. Realise the package script-pkg.nix
5. Run the executable

I repeated the above while using --name, as well.

I suspect --executable would have no meaningful effect if combined with
--unpack, but I have not tried it.

											
										
										
											2020-09-18 18:36:17 +03:00
+								    Set the executable bit on the downloaded file.
-												Replace the trailing markdown spaces by a backslash

They are equivalent according to
<https://spec.commonmark.org/0.29/#hard-line-breaks>,
and the trailing spaces tend to be a pain (because the make git
complain, editors tend to want to remove them − the `.editorconfig`
actually specifies that − etc..).

											
										
										
											2021-04-23 15:30:42 +03:00
+								  - `--name` *name*\
-												Convert commands

											
										
										
											2020-07-23 13:58:42 +03:00
+								    Override the name of the file in the Nix store. By default, this is
-												<replaceable> -> <emphasis>

Pandoc doesn't know <replaceable> so let's force it to be rendered as
italics.

											
										
										
											2020-07-23 15:28:05 +03:00
+								    `hash-basename`, where *basename* is the last component of *url*.
 								    Overriding the name is necessary when *basename* contains characters
-												Convert commands

											
										
										
											2020-07-23 13:58:42 +03:00
+								    that are not allowed in Nix store paths.
 								# Examples
-												Enable syntax highlighting

											
										
										
											2020-07-31 16:43:25 +03:00
+								```console
 								$ nix-prefetch-url ftp://ftp.gnu.org/pub/gnu/hello/hello-2.10.tar.gz
 ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i
 								```
 								```console
 								$ nix-prefetch-url --print-path mirror://gnu/hello/hello-2.10.tar.gz
 ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i
 								/nix/store/3x7dwzq014bblazs7kq20p9hyzz0qh8g-hello-2.10.tar.gz
 								```
 								```console
 								$ nix-prefetch-url --unpack --print-path https://github.com/NixOS/patchelf/archive/0.8.tar.gz
 agjlv0hrv7fxnx9ngipx14gyncbkllxrp9cccnh3a50fxcmy7
 								/nix/store/19zrmhm3m40xxaw81c8cqm6aljgrnwj2-0.8.tar.gz
 								```