doc/build-helpers/fetchers.chapter.md

   1 # Fetchers {#chap-pkgs-fetchers}
   2
   3 Building software with Nix often requires downloading source code and other files from the internet.
   4 To this end, we use functions that we call _fetchers_, which obtain remote sources via various protocols and services.
   5
   6 Nix provides built-in fetchers such as [`builtins.fetchTarball`](https://nixos.org/manual/nix/stable/language/builtins.html#builtins-fetchTarball).
   7 Nixpkgs provides its own fetchers, which work differently:
   8
   9 - A built-in fetcher will download and cache files at evaluation time and produce a [store path](https://nixos.org/manual/nix/stable/glossary#gloss-store-path).
  10   A Nixpkgs fetcher will create a ([fixed-output](https://nixos.org/manual/nix/stable/glossary#gloss-fixed-output-derivation)) [derivation](https://nixos.org/manual/nix/stable/glossary#gloss-derivation), and files are downloaded at build time.
  11 - Built-in fetchers will invalidate their cache after [`tarball-ttl`](https://nixos.org/manual/nix/stable/command-ref/conf-file#conf-tarball-ttl) expires, and will require network activity to check if the cache entry is up to date.
  12   Nixpkgs fetchers only re-download if the specified hash changes or the store object is not available.
  13 - Built-in fetchers do not use [substituters](https://nixos.org/manual/nix/stable/command-ref/conf-file#conf-substituters).
  14   Derivations produced by Nixpkgs fetchers will use any configured binary cache transparently.
  15
  16 This significantly reduces the time needed to evaluate Nixpkgs, and allows [Hydra](https://nixos.org/hydra) to retain and re-distribute sources used by Nixpkgs in the [public binary cache](https://cache.nixos.org).
  17 For these reasons, Nix's built-in fetchers are not allowed in Nixpkgs.
  18
  19 The following table summarises the differences:
  20
  21 | Fetchers | Download | Output | Cache | Re-download when |
  22 |-|-|-|-|-|
  23 | `builtins.fetch*` | evaluation time | store path | `/nix/store`, `~/.cache/nix` | `tarball-ttl` expires, cache miss in `~/.cache/nix`, output store object not in local store |
  24 | `pkgs.fetch*` | build time | derivation | `/nix/store`, substituters | output store object not available |
  25
  26 :::{.tip}
  27 `pkgs.fetchFrom*` helpers retrieve _snapshots_ of version-controlled sources, as opposed to the entire version history, which is more efficient.
  28 `pkgs.fetchgit` by default also has the same behaviour, but can be changed through specific attributes given to it.
  29 :::
  30
  31 ## Caveats {#chap-pkgs-fetchers-caveats}
  32
  33 Because Nixpkgs fetchers are fixed-output derivations, an [output hash](https://nixos.org/manual/nix/stable/language/advanced-attributes#adv-attr-outputHash) has to be specified, usually indirectly through a `hash` attribute.
  34 This hash refers to the derivation output, which can be different from the remote source itself!
  35
  36 This has the following implications that you should be aware of:
  37
  38 - Use Nix (or Nix-aware) tooling to produce the output hash.
  39
  40 - When changing any fetcher parameters, always update the output hash.
  41   Use one of the methods from [](#sec-pkgs-fetchers-updating-source-hashes).
  42   Otherwise, existing store objects that match the output hash will be re-used rather than fetching new content.
  43
  44   :::{.note}
  45   A similar problem arises while testing changes to a fetcher's implementation.
  46   If the output of the derivation already exists in the Nix store, test failures can go undetected.
  47   The [`invalidateFetcherByDrvHash`](#tester-invalidateFetcherByDrvHash) function helps prevent reusing cached derivations.
  48   :::
  49
  50 ## Updating source hashes {#sec-pkgs-fetchers-updating-source-hashes}
  51
  52 There are several ways to obtain the hash corresponding to a remote source.
  53 Unless you understand how the fetcher you're using calculates the hash from the downloaded contents, you should use [the fake hash method](#sec-pkgs-fetchers-updating-source-hashes-fakehash-method).
  54
  55 1. []{#sec-pkgs-fetchers-updating-source-hashes-fakehash-method} The fake hash method: In your package recipe, set the hash to one of
  56
  57    - `""`
  58    - `lib.fakeHash`
  59    - `lib.fakeSha256`
  60    - `lib.fakeSha512`
  61
  62    Attempt to build, extract the calculated hashes from error messages, and put them into the recipe.
  63
  64    :::{.warning}
  65    You must use one of these four fake hashes and not some arbitrarily-chosen hash.
  66    See [](#sec-pkgs-fetchers-secure-hashes) for details.
  67    :::
  68
  69    :::{.example #ex-fetchers-update-fod-hash}
  70    # Update source hash with the fake hash method
  71
  72    Consider the following recipe that produces a plain file:
  73
  74    ```nix
  75    { fetchurl }:
  76    fetchurl {
  77      url = "https://raw.githubusercontent.com/NixOS/nixpkgs/23.05/.version";
  78      hash = "sha256-ZHl1emidXVojm83LCVrwULpwIzKE/mYwfztVkvpruOM=";
  79    }
  80    ```
  81
  82    A common mistake is to update a fetcher parameter, such as `url`, without updating the hash:
  83
  84    ```nix
  85    { fetchurl }:
  86    fetchurl {
  87      url = "https://raw.githubusercontent.com/NixOS/nixpkgs/23.11/.version";
  88      hash = "sha256-ZHl1emidXVojm83LCVrwULpwIzKE/mYwfztVkvpruOM=";
  89    }
  90    ```
  91
  92    **This will produce the same output as before!**
  93    Set the hash to an empty string:
  94
  95    ```nix
  96    { fetchurl }:
  97    fetchurl {
  98      url = "https://raw.githubusercontent.com/NixOS/nixpkgs/23.11/.version";
  99      hash = "";
 100    }
 101    ```
 102
 103    When building the package, use the error message to determine the correct hash:
 104
 105    ```shell
 106    $ nix-build
 107    (some output removed for clarity)
 108    error: hash mismatch in fixed-output derivation '/nix/store/7yynn53jpc93l76z9zdjj4xdxgynawcw-version.drv':
 109            specified: sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
 110                got:    sha256-BZqI7r0MNP29yGH5+yW2tjU9OOpOCEvwWKrWCv5CQ0I=
 111    error: build of '/nix/store/bqdjcw5ij5ymfbm41dq230chk9hdhqff-version.drv' failed
 112    ```
 113    :::
 114
 115 2. Prefetch the source with [`nix-prefetch-<type> <URL>`](https://search.nixos.org/packages?buckets={%22package_attr_set%22%3A[%22No%20package%20set%22]%2C%22package_license_set%22%3A[]%2C%22package_maintainers_set%22%3A[]%2C%22package_platforms%22%3A[]}&query=nix-prefetch), where `<type>` is one of
 116
 117    - `url`
 118    - `git`
 119    - `hg`
 120    - `cvs`
 121    - `bzr`
 122    - `svn`
 123
 124    The hash is printed to stdout.
 125
 126 3. Prefetch by package source (with `nix-prefetch-url '<nixpkgs>' -A <package>.src`, where `<package>` is package attribute name).
 127    The hash is printed to stdout.
 128
 129    This works well when you've upgraded the existing package version and want to find out new hash, but is useless if the package can't be accessed by attribute or the package has multiple sources (`.srcs`, architecture-dependent sources, etc).
 130
 131 4. Upstream hash: use it when upstream provides `sha256` or `sha512`.
 132    Don't use it when upstream provides `md5`, compute `sha256` instead.
 133
 134    A little nuance is that `nix-prefetch-*` tools produce hashes with the `nix32` encoding (a Nix-specific base32 adaptation), but upstream usually provides hexadecimal (`base16`) encoding.
 135    Fetchers understand both formats.
 136    Nixpkgs does not standardise on any one format.
 137
 138    You can convert between hash formats with [`nix-hash`](https://nixos.org/manual/nix/stable/command-ref/nix-hash).
 139
 140 5. Extract the hash from a local source archive with `sha256sum`.
 141    Use `nix-prefetch-url file:///path/to/archive` if you want the custom Nix `base32` hash.
 142
 143 ## Obtaining hashes securely {#sec-pkgs-fetchers-secure-hashes}
 144
 145 It's always a good idea to avoid Man-in-the-Middle (MITM) attacks when downloading source contents.
 146 Otherwise, you could unknowingly download malware instead of the intended source, and instead of the actual source hash, you'll end up using the hash of malware.
 147 Here are security considerations for this scenario:
 148
 149 - `http://` URLs are not secure to prefetch hashes.
 150
 151 - Upstream hashes should be obtained via a secure protocol.
 152
 153 - `https://` URLs give you more protections when using `nix-prefetch-*` or for upstream hashes.
 154
 155 - `https://` URLs are secure when using the [fake hash method](#sec-pkgs-fetchers-updating-source-hashes-fakehash-method) *only if* you use one of the listed fake hashes.
 156   If you use any other hash, the download will be exposed to MITM attacks even if you use HTTPS URLs.
 157
 158   In more concrete terms, if you use any other hash, the [`--insecure` flag](https://curl.se/docs/manpage.html#-k) will be passed to the underlying call to `curl` when downloading content.
 159
 160 ## Proxy usage {#sec-pkgs-fetchers-proxy}
 161
 162 Nixpkgs fetchers can make use of a http(s) proxy. Each fetcher will automatically inherit proxy-related environment variables (`http_proxy`, `https_proxy`, etc) via [impureEnvVars](https://nixos.org/manual/nix/stable/language/advanced-attributes#adv-attr-impureEnvVars).
 163
 164 The environment variable `NIX_SSL_CERT_FILE` is also inherited in fetchers, and can be used to provide a custom certificate bundle to fetchers. This is usually required for a https proxy to work without certificate validation errors.
 165
 166 []{#fetchurl}
 167 ## `fetchurl` {#sec-pkgs-fetchers-fetchurl}
 168
 169 `fetchurl` returns a [fixed-output derivation](https://nixos.org/manual/nix/stable/glossary.html#gloss-fixed-output-derivation) which downloads content from a given URL and stores the unaltered contents within the Nix store.
 170
 171 It uses {manpage}`curl(1)` internally, and allows its behaviour to be modified by specifying a few attributes in the argument to `fetchurl` (see the documentation for attributes `curlOpts`, `curlOptsList`, and `netrcPhase`).
 172
 173 The resulting [store path](https://nixos.org/manual/nix/stable/store/store-path) is determined by the hash given to `fetchurl`, and also the `name` (or `pname` and `version`) values.
 174
 175 If neither `name` nor `pname` and `version` are specified when calling `fetchurl`, it will default to using the [basename](https://nixos.org/manual/nix/stable/language/builtins.html#builtins-baseNameOf) of `url` or the first element of `urls`.
 176 If `pname` and `version` are specified, `fetchurl` will use those values and will ignore `name`, even if it is also specified.
 177
 178 ### Inputs {#sec-pkgs-fetchers-fetchurl-inputs}
 179
 180 `fetchurl` requires an attribute set with the following attributes:
 181
 182 `url` (String; _optional_)
 183 : The URL to download from.
 184
 185   :::{.note}
 186   Either `url` or `urls` must be specified, but not both.
 187   :::
 188
 189   All URLs of the format [specified here](https://curl.se/docs/url-syntax.html#rfc-3986-plus) are supported.
 190
 191   _Default value:_ `""`.
 192
 193 `urls` (List of String; _optional_)
 194 : A list of URLs, specifying download locations for the same content.
 195   Each URL will be tried in order until one of them succeeds with some content or all of them fail.
 196   See [](#ex-fetchers-fetchurl-nixpkgs-version-multiple-urls) to understand how this attribute affects the behaviour of `fetchurl`.
 197
 198   :::{.note}
 199   Either `url` or `urls` must be specified, but not both.
 200   :::
 201
 202   _Default value:_ `[]`.
 203
 204 `hash` (String; _optional_)
 205 : Hash of the derivation output of `fetchurl`, following the format for integrity metadata as defined by [SRI](https://www.w3.org/TR/SRI/).
 206   For more information, see [](#chap-pkgs-fetchers-caveats).
 207
 208   :::{.note}
 209   It is recommended that you use the `hash` attribute instead of the other hash-specific attributes that exist for backwards compatibility.
 210
 211   If `hash` is not specified, you must specify `outputHash` and `outputHashAlgo`, or one of `sha512`, `sha256`, or `sha1`.
 212   :::
 213
 214   _Default value:_ `""`.
 215
 216 `outputHash` (String; _optional_)
 217 : Hash of the derivation output of `fetchurl` in the format expected by Nix.
 218   See [the documentation on the Nix manual](https://nixos.org/manual/nix/stable/language/advanced-attributes.html#adv-attr-outputHash) for more information about its format.
 219
 220   :::{.note}
 221   It is recommended that you use the `hash` attribute instead.
 222
 223   If `outputHash` is specified, you must also specify `outputHashAlgo`.
 224   :::
 225
 226   _Default value:_ `""`.
 227
 228 `outputHashAlgo` (String; _optional_)
 229 : Algorithm used to generate the value specified in `outputHash`.
 230   See [the documentation on the Nix manual](https://nixos.org/manual/nix/stable/language/advanced-attributes.html#adv-attr-outputHashAlgo) for more information about the values it supports.
 231
 232   :::{.note}
 233   It is recommended that you use the `hash` attribute instead.
 234
 235   The value specified in `outputHashAlgo` will be ignored if `outputHash` isn't also specified.
 236   :::
 237
 238   _Default value:_ `""`.
 239
 240 `sha1` (String; _optional_)
 241 : SHA-1 hash of the derivation output of `fetchurl` in the format expected by Nix.
 242   See [the documentation on the Nix manual](https://nixos.org/manual/nix/stable/language/advanced-attributes.html#adv-attr-outputHash) for more information about its format.
 243
 244   :::{.note}
 245   It is recommended that you use the `hash` attribute instead.
 246   :::
 247
 248   _Default value:_ `""`.
 249
 250 `sha256` (String; _optional_)
 251 : SHA-256 hash of the derivation output of `fetchurl` in the format expected by Nix.
 252   See [the documentation on the Nix manual](https://nixos.org/manual/nix/stable/language/advanced-attributes.html#adv-attr-outputHash) for more information about its format.
 253
 254   :::{.note}
 255   It is recommended that you use the `hash` attribute instead.
 256   :::
 257
 258   _Default value:_ `""`.
 259
 260 `sha512` (String; _optional_)
 261 : SHA-512 hash of the derivation output of `fetchurl` in the format expected by Nix.
 262   See [the documentation on the Nix manual](https://nixos.org/manual/nix/stable/language/advanced-attributes.html#adv-attr-outputHash) for more information about its format.
 263
 264   :::{.note}
 265   It is recommended that you use the `hash` attribute instead.
 266   :::
 267
 268   _Default value:_ `""`.
 269
 270 `name` (String; _optional_)
 271 : The symbolic name of the downloaded file when saved in the Nix store.
 272   See [the `fetchurl` overview](#sec-pkgs-fetchers-fetchurl) for details on how the name of the file is decided.
 273
 274   _Default value:_ `""`.
 275
 276 `pname` (String; _optional_)
 277 : A base name, which will be combined with `version` to form the symbolic name of the downloaded file when saved in the Nix store.
 278   See [the `fetchurl` overview](#sec-pkgs-fetchers-fetchurl) for details on how the name of the file is decided.
 279
 280   :::{.note}
 281   If `pname` is specified, you must also specify `version`, otherwise `fetchurl` will ignore the value of `pname`.
 282   :::
 283
 284   _Default value:_ `""`.
 285
 286 `version` (String; _optional_)
 287 : A version, which will be combined with `pname` to form the symbolic name of the downloaded file when saved in the Nix store.
 288   See [the `fetchurl` overview](#sec-pkgs-fetchers-fetchurl) for details on how the name of the file is decided.
 289
 290   _Default value:_ `""`.
 291
 292 `recursiveHash` (Boolean; _optional_) []{#sec-pkgs-fetchers-fetchurl-inputs-recursiveHash}
 293 : If set to `true`, will signal to Nix that the hash given to `fetchurl` was calculated using the `"recursive"` mode.
 294   See [the documentation on the Nix manual](https://nixos.org/manual/nix/stable/language/advanced-attributes.html#adv-attr-outputHashMode) for more information about the existing modes.
 295
 296   By default, `fetchurl` uses `"recursive"` mode when the `executable` attribute is set to `true`, so you don't need to specify `recursiveHash` in this case.
 297
 298   _Default value:_ `false`.
 299
 300 `executable` (Boolean; _optional_)
 301 : If `true`, sets the executable bit on the downloaded file.
 302
 303   _Default value_: `false`.
 304
 305 `downloadToTemp` (Boolean; _optional_) []{#sec-pkgs-fetchers-fetchurl-inputs-downloadToTemp}
 306 : If `true`, saves the downloaded file to a temporary location instead of the expected Nix store location.
 307   This is useful when used in conjunction with `postFetch` attribute, otherwise `fetchurl` will not produce any meaningful output.
 308
 309   The location of the downloaded file will be set in the `$downloadedFile` variable, which should be used by the script in the `postFetch` attribute.
 310   See [](#ex-fetchers-fetchurl-nixpkgs-version-postfetch) to understand how to work with this attribute.
 311
 312   _Default value:_ `false`.
 313
 314 `postFetch` (String; _optional_)
 315 : Script executed after the file has been downloaded successfully, and before `fetchurl` finishes running.
 316   Useful for post-processing, to check or transform the file in some way.
 317   See [](#ex-fetchers-fetchurl-nixpkgs-version-postfetch) to understand how to work with this attribute.
 318
 319   _Default value:_ `""`.
 320
 321 `netrcPhase` (String or Null; _optional_)
 322 : Script executed to create a {manpage}`netrc(5)` file to be used with {manpage}`curl(1)`.
 323   The script should create the `netrc` file (note that it does not begin with a ".") in the directory it's currently running in (`$PWD`).
 324
 325   The script is executed during the setup done by `fetchurl` before it runs any of its code to download the specified content.
 326
 327   :::{.note}
 328   If specified, `fetchurl` will automatically alter its invocation of {manpage}`curl(1)` to use the `netrc` file, so you don't need to add anything to `curlOpts` or `curlOptsList`.
 329   :::
 330
 331   :::{.caution}
 332   Since `netrcPhase` needs to be specified in your source Nix code, any secrets that you put directly in it will be world-readable by design (both in your source code, and when the derivation gets created in the Nix store).
 333
 334   If you want to avoid this behaviour, see the documentation of `netrcImpureEnvVars` for an alternative way of dealing with these secrets.
 335   :::
 336
 337   _Default value_: `null`.
 338
 339 `netrcImpureEnvVars` (List of String; _optional_)
 340 : If specified, `fetchurl` will add these environment variable names to the list of [impure environment variables](https://nixos.org/manual/nix/stable/language/advanced-attributes.html#adv-attr-impureEnvVars), which will be passed from the environment of the calling user to the builder running the `fetchurl` code.
 341
 342   This is useful when used with `netrcPhase` to hide any secrets that are used in it, because the script in `netrcPhase` only needs to reference the environment variables with the secrets in them instead.
 343   However, note that these are called _impure_ variables for a reason:
 344   the environment that starts the build needs to have these variables declared for everything to work properly, which means that additional setup is required outside what Nix controls.
 345
 346   _Default value:_ `[]`.
 347
 348 `curlOpts` (String; _optional_)
 349 : If specified, this value will be appended to the invocation of {manpage}`curl(1)` when downloading the URL(s) given to `fetchurl`.
 350   Multiple arguments can be separated by spaces normally, but values with whitespaces will be interpreted as multiple arguments (instead of a single value), even if the value is escaped.
 351   See `curlOptsList` for a way to pass values with whitespaces in them.
 352
 353   _Default value:_ `""`.
 354
 355 `curlOptsList` (List of String; _optional_)
 356 : If specified, each element of this list will be passed as an argument to the invocation of {manpage}`curl(1)` when downloading the URL(s) given to `fetchurl`.
 357   This allows passing values that contain spaces, with no escaping needed.
 358
 359   _Default value:_ `[]`.
 360
 361 `showURLs` (Boolean; _optional_)
 362 : If set to `true`, this will stop `fetchurl` from downloading anything at all.
 363   Instead, it will output a list of all the URLs it would've used to download the content (after resolving `mirror://` URLs, for example).
 364   This is useful for debugging.
 365
 366   _Default value:_ `false`.
 367
 368 `meta` (Attribute Set; _optional_)
 369 : Specifies any [meta-attributes](#chap-meta) for the derivation returned by `fetchurl`.
 370
 371   _Default value:_ `{}`.
 372
 373 `passthru` (Attribute Set; _optional_)
 374 : Specifies any extra [`passthru`](#chap-passthru) attributes for the derivation returned by `fetchurl`.
 375   Note that `fetchurl` defines [`passthru` attributes of its own](#ssec-pkgs-fetchers-fetchurl-passthru-outputs).
 376   Attributes specified in `passthru` can override the default attributes returned by `fetchurl`.
 377
 378   _Default value:_ `{}`.
 379
 380 `preferLocalBuild` (Boolean; _optional_)
 381 : This is the same attribute as [defined in the Nix manual](https://nixos.org/manual/nix/stable/language/advanced-attributes.html#adv-attr-preferLocalBuild).
 382   It is `true` by default because making a remote machine download the content just duplicates network traffic (since the local machine might download the results from the derivation anyway), but this could be useful in cases where network access is restricted on local machines.
 383
 384   _Default value:_ `true`.
 385
 386 `nativeBuildInputs` (List of Attribute Set; _optional_)
 387 : Additional packages needed to download the content.
 388   This is useful if you need extra packages for `postFetch` or `netrcPhase`, for example.
 389   Has the same semantics as in [](#var-stdenv-nativeBuildInputs).
 390   See [](#ex-fetchers-fetchurl-nixpkgs-version-postfetch) to understand how this can be used with `postFetch`.
 391
 392   _Default value:_ `[]`.
 393
 394 ### Passthru outputs {#ssec-pkgs-fetchers-fetchurl-passthru-outputs}
 395
 396 `fetchurl` also defines its own [`passthru`](#chap-passthru) attributes:
 397
 398 `url` (String)
 399
 400 : The same `url` attribute passed in the argument to `fetchurl`.
 401
 402 ### Examples {#ssec-pkgs-fetchers-fetchurl-examples}
 403
 404 :::{.example #ex-fetchers-fetchurl-nixpkgs-version}
 405 # Using `fetchurl` to download a file
 406
 407 The following package downloads a small file from a URL and shows the most common way to use `fetchurl`:
 408
 409 ```nix
 410 { fetchurl }:
 411 fetchurl {
 412   url = "https://raw.githubusercontent.com/NixOS/nixpkgs/23.11/.version";
 413   hash = "sha256-BZqI7r0MNP29yGH5+yW2tjU9OOpOCEvwWKrWCv5CQ0I=";
 414 }
 415 ```
 416
 417 After building the package, the file will be downloaded and place into the Nix store:
 418
 419 ```shell
 420 $ nix-build
 421 (output removed for clarity)
 422 /nix/store/4g9y3x851wqrvim4zcz5x2v3zivmsq8n-version
 423
 424 $ cat /nix/store/4g9y3x851wqrvim4zcz5x2v3zivmsq8n-version
 425 23.11
 426 ```
 427 :::
 428
 429 :::{.example #ex-fetchers-fetchurl-nixpkgs-version-multiple-urls}
 430 # Using `fetchurl` to download a file with multiple possible URLs
 431
 432 The following package adapts [](#ex-fetchers-fetchurl-nixpkgs-version) to use multiple URLs.
 433 The first URL was crafted to intentionally return an error to illustrate how `fetchurl` will try multiple URLs until it finds one that works (or all URLs fail).
 434
 435 ```nix
 436 { fetchurl }:
 437 fetchurl {
 438   urls = [
 439     "https://raw.githubusercontent.com/NixOS/nixpkgs/23.11/does-not-exist"
 440     "https://raw.githubusercontent.com/NixOS/nixpkgs/23.11/.version"
 441   ];
 442   hash = "sha256-BZqI7r0MNP29yGH5+yW2tjU9OOpOCEvwWKrWCv5CQ0I=";
 443 }
 444 ```
 445
 446 After building the package, both URLs will be used to download the file:
 447
 448 ```shell
 449 $ nix-build
 450 (some output removed for clarity)
 451 trying https://raw.githubusercontent.com/NixOS/nixpkgs/23.11/does-not-exist
 452 (some output removed for clarity)
 453 curl: (22) The requested URL returned error: 404
 454
 455 trying https://raw.githubusercontent.com/NixOS/nixpkgs/23.11/.version
 456 (some output removed for clarity)
 457 /nix/store/n9asny31z32q7sdw6a8r1gllrsfy53kl-does-not-exist
 458
 459 $ cat /nix/store/n9asny31z32q7sdw6a8r1gllrsfy53kl-does-not-exist
 460 23.11
 461 ```
 462
 463 However, note that the name of the file was derived from the first URL (this is further explained in [the `fetchurl` overview](#sec-pkgs-fetchers-fetchurl)).
 464 To ensure the result will have the same name regardless of which URLs are used, we can modify the package:
 465
 466 ```nix
 467 { fetchurl }:
 468 fetchurl {
 469   name = "nixpkgs-version";
 470   urls = [
 471     "https://raw.githubusercontent.com/NixOS/nixpkgs/23.11/does-not-exist"
 472     "https://raw.githubusercontent.com/NixOS/nixpkgs/23.11/.version"
 473   ];
 474   hash = "sha256-BZqI7r0MNP29yGH5+yW2tjU9OOpOCEvwWKrWCv5CQ0I=";
 475 }
 476 ```
 477
 478 After building the package, the result will have the name we specified:
 479
 480 ```shell
 481 $ nix-build
 482 (output removed for clarity)
 483 /nix/store/zczb6wl3al6jm9sm5h3pr6nqn0i5ji9z-nixpkgs-version
 484 ```
 485 :::
 486
 487 :::{.example #ex-fetchers-fetchurl-nixpkgs-version-postfetch}
 488 # Manipulating the content downloaded by `fetchurl`
 489
 490 It might be useful to manipulate the content downloaded by `fetchurl` directly in its derivation.
 491 In this example, we'll adapt [](#ex-fetchers-fetchurl-nixpkgs-version) to append the result of running the `hello` package to the contents we download, purely to illustrate how to manipulate the content.
 492
 493 ```nix
 494 { fetchurl, hello, lib }:
 495 fetchurl {
 496   url = "https://raw.githubusercontent.com/NixOS/nixpkgs/23.11/.version";
 497
 498   nativeBuildInputs = [ hello ];
 499
 500   downloadToTemp = true;
 501   postFetch = ''
 502     ${lib.getExe hello} >> $downloadedFile
 503     mv $downloadedFile $out
 504   '';
 505
 506   hash = "sha256-ceooQQYmDx5+0nfg40uU3NNI2yKrixP7HZ/xLZUNv+w=";
 507 }
 508 ```
 509
 510 After building the package, the resulting file will have "Hello, world!" appended to it:
 511
 512 ```shell
 513 $ nix-build
 514 (output removed for clarity)
 515 /nix/store/ifi6pp7q0ag5h7c5v9h1c1c7bhd10c7f-version
 516
 517 $ cat /nix/store/ifi6pp7q0ag5h7c5v9h1c1c7bhd10c7f-version
 518 23.11
 519 Hello, world!
 520 ```
 521
 522 Note that the `hash` specified in the package is different than the hash specified in [](#ex-fetchers-fetchurl-nixpkgs-version), because the contents of the output have changed (even though the actual file that was downloaded is the same).
 523 See [](#chap-pkgs-fetchers-caveats) for more details on how to work with the `hash` attribute when the output changes.
 524 :::
 525
 526 ## `fetchzip` {#sec-pkgs-fetchers-fetchzip}
 527
 528 Returns a [fixed-output derivation](https://nixos.org/manual/nix/stable/glossary.html#gloss-fixed-output-derivation) which downloads an archive from a given URL and decompresses it.
 529
 530 Despite its name, `fetchzip` is not limited to `.zip` files but can also be used with [various compressed tarball formats](#tar-files) by default.
 531 This can extended by specifying additional attributes, see [](#ex-fetchers-fetchzip-rar-archive) to understand how to do that.
 532
 533 ### Inputs {#sec-pkgs-fetchers-fetchzip-inputs}
 534
 535 `fetchzip` requires an attribute set, and most attributes are passed to the underlying call to [`fetchurl`](#sec-pkgs-fetchers-fetchurl).
 536
 537 The attributes below are treated differently by `fetchzip` when compared to what `fetchurl` expects:
 538
 539 `name` (String; _optional_)
 540 : Works as defined in `fetchurl`, but has a different default value than `fetchurl`.
 541
 542   _Default value:_ `"source"`.
 543
 544 `nativeBuildInputs` (List of Attribute Set; _optional_)
 545 : Works as defined in `fetchurl`, but it is also augmented by `fetchzip` to include packages to deal with additional archives (such as `.zip`).
 546
 547   _Default value:_ `[]`.
 548
 549 `postFetch` (String; _optional_)
 550 : Works as defined in `fetchurl`, but it is also augmented with the code needed to make `fetchzip` work.
 551
 552   :::{.caution}
 553   It is only safe to modify files in `$out` in `postFetch`.
 554   Consult the implementation of `fetchzip` for anything more involved.
 555   :::
 556
 557   _Default value:_ `""`.
 558
 559 `stripRoot` (Boolean; _optional_)
 560 : If `true`, the decompressed contents are moved one level up the directory tree.
 561
 562   This is useful for archives that decompress into a single directory which commonly includes some values that change with time, such as version numbers.
 563   When this is the case (and `stripRoot` is `true`), `fetchzip` will remove this directory and make the decompressed contents available in the top-level directory.
 564
 565   [](#ex-fetchers-fetchzip-simple-striproot) shows what this attribute does.
 566
 567   This attribute is **not** passed through to `fetchurl`.
 568
 569   _Default value:_ `true`.
 570
 571 `extension` (String or Null; _optional_)
 572 : If set, the archive downloaded by `fetchzip` will be renamed to a filename with the extension specified in this attribute.
 573
 574   This is useful when making `fetchzip` support additional types of archives, because the implementation may use the extension of an archive to determine whether they can decompress it.
 575   If the URL you're using to download the contents doesn't end with the extension associated with the archive, use this attribute to fix the filename of the archive.
 576
 577   This attribute is **not** passed through to `fetchurl`.
 578
 579   _Default value:_ `null`.
 580
 581 `recursiveHash` (Boolean; _optional_)
 582 : Works [as defined in `fetchurl`](#sec-pkgs-fetchers-fetchurl-inputs-recursiveHash), but its default value is different than for `fetchurl`.
 583
 584   _Default value:_ `true`.
 585
 586 `downloadToTemp` (Boolean; _optional_)
 587 : Works [as defined in `fetchurl`](#sec-pkgs-fetchers-fetchurl-inputs-downloadToTemp), but its default value is different than for `fetchurl`.
 588
 589   _Default value:_ `true`.
 590
 591 `extraPostFetch` **DEPRECATED**
 592 : This attribute is deprecated.
 593   Please use `postFetch` instead.
 594
 595   This attribute is **not** passed through to `fetchurl`.
 596
 597 ### Examples {#sec-pkgs-fetchers-fetchzip-examples}
 598
 599 ::::{.example #ex-fetchers-fetchzip-simple-striproot}
 600 # Using `fetchzip` to output contents directly
 601
 602 The following recipe shows how to use `fetchzip` to decompress a `.tar.gz` archive:
 603
 604 ```nix
 605 { fetchzip }:
 606 fetchzip {
 607   url = "https://github.com/NixOS/patchelf/releases/download/0.18.0/patchelf-0.18.0.tar.gz";
 608   hash = "sha256-3ABYlME9R8klcpJ7MQpyFEFwHmxDDEzIYBqu/CpDYmg=";
 609 }
 610 ```
 611
 612 This archive has all its contents in a directory named `patchelf-0.18.0`.
 613 This means that after decompressing, you'd have to enter this directory to see the contents of the archive.
 614 However, `fetchzip` makes this easier through the attribute `stripRoot` (enabled by default).
 615
 616 After building the recipe, the derivation output will show all the files in the archive at the top level:
 617
 618 ```shell
 619 $ nix-build
 620 (output removed for clarity)
 621 /nix/store/1b7h3fvmgrcddvs0m299hnqxlgli1yjw-source
 622
 623 $ ls /nix/store/1b7h3fvmgrcddvs0m299hnqxlgli1yjw-source
 624 aclocal.m4  completions  configure.ac  m4           Makefile.in  patchelf.spec     README.md  tests
 625 build-aux   configure    COPYING       Makefile.am  patchelf.1   patchelf.spec.in  src        version
 626 ```
 627
 628 If `stripRoot` is set to `false`, the derivation output will be the decompressed archive as-is:
 629
 630 ```nix
 631 { fetchzip }:
 632 fetchzip {
 633   url = "https://github.com/NixOS/patchelf/releases/download/0.18.0/patchelf-0.18.0.tar.gz";
 634   hash = "sha256-uv3FuKE4DqpHT3yfE0qcnq0gYjDNQNKZEZt2+PUAneg=";
 635   stripRoot = false;
 636 }
 637 ```
 638
 639 :::{.caution}
 640 The hash changed!
 641 Whenever changing attributes of a Nixpkgs fetcher, [remember to invalidate the hash](#chap-pkgs-fetchers-caveats), otherwise you won't get the results you're expecting!
 642 :::
 643
 644 After building the recipe:
 645
 646 ```shell
 647 $ nix-build
 648 (output removed for clarity)
 649 /nix/store/2hy5bxw7xgbgxkn0i4x6hjr8w3dbx16c-source
 650
 651 $ ls /nix/store/2hy5bxw7xgbgxkn0i4x6hjr8w3dbx16c-source
 652 patchelf-0.18.0
 653 ```
 654 ::::
 655
 656 ::::{.example #ex-fetchers-fetchzip-rar-archive}
 657 # Using `fetchzip` to decompress a `.rar` file
 658
 659 The `unrar` package provides a [setup hook](#ssec-setup-hooks) to decompress `.rar` archives during the [unpack phase](#ssec-unpack-phase), which can be used with `fetchzip` to decompress those archives:
 660
 661 ```nix
 662 { fetchzip, unrar }:
 663 fetchzip {
 664   url = "https://archive.org/download/SpaceCadet_Plus95/Space_Cadet.rar";
 665   hash = "sha256-fC+zsR8BY6vXpUkVd6i1jF0IZZxVKVvNi6VWCKT+pA4=";
 666   stripRoot = false;
 667   nativeBuildInputs = [ unrar ];
 668 }
 669 ```
 670
 671 Since this particular `.rar` file doesn't put its contents in a directory inside the archive, `stripRoot` must be set to `false`.
 672
 673 After building the recipe, the derivation output will show the decompressed files:
 674
 675 ```shell
 676 $ nix-build
 677 (output removed for clarity)
 678 /nix/store/zpn7knxfva6rfjja2gbb4p3l9w1f0d36-source
 679
 680 $ ls /nix/store/zpn7knxfva6rfjja2gbb4p3l9w1f0d36-source
 681 FONT.DAT      PINBALL.DAT  PINBALL.EXE  PINBALL2.MID  TABLE.BMP    WMCONFIG.EXE
 682 MSCREATE.DIR  PINBALL.DOC  PINBALL.MID  Sounds       WAVEMIX.INF
 683 ```
 684 ::::
 685
 686 ## `fetchpatch` {#fetchpatch}
 687
 688 `fetchpatch` works very similarly to `fetchurl` with the same arguments expected. It expects patch files as a source and performs normalization on them before computing the checksum. For example, it will remove comments or other unstable parts that are sometimes added by version control systems and can change over time.
 689
 690 - `relative`: Similar to using `git-diff`'s `--relative` flag, only keep changes inside the specified directory, making paths relative to it.
 691 - `stripLen`: Remove the first `stripLen` components of pathnames in the patch.
 692 - `decode`: Pipe the downloaded data through this command before processing it as a patch.
 693 - `extraPrefix`: Prefix pathnames by this string.
 694 - `excludes`: Exclude files matching these patterns (applies after the above arguments).
 695 - `includes`: Include only files matching these patterns (applies after the above arguments).
 696 - `revert`: Revert the patch.
 697
 698 Note that because the checksum is computed after applying these effects, using or modifying these arguments will have no effect unless the `hash` argument is changed as well.
 699
 700
 701 Most other fetchers return a directory rather than a single file.
 702
 703
 704 ## `fetchDebianPatch` {#fetchdebianpatch}
 705
 706 A wrapper around `fetchpatch`, which takes:
 707 - `patch` and `hash`: the patch's filename,
 708   and its hash after normalization by `fetchpatch` ;
 709 - `pname`: the Debian source package's name ;
 710 - `version`: the upstream version number ;
 711 - `debianRevision`: the [Debian revision number] if applicable ;
 712 - the `area` of the Debian archive: `main` (default), `contrib`, or `non-free`.
 713
 714 Here is an example of `fetchDebianPatch` in action:
 715
 716 ```nix
 717 { lib
 718 , fetchDebianPatch
 719 , buildPythonPackage
 720 }:
 721
 722 buildPythonPackage rec {
 723   pname = "pysimplesoap";
 724   version = "1.16.2";
 725   src = <...>;
 726
 727   patches = [
 728     (fetchDebianPatch {
 729       inherit pname version;
 730       debianRevision = "5";
 731       name = "Add-quotes-to-SOAPAction-header-in-SoapClient.patch";
 732       hash = "sha256-xA8Wnrpr31H8wy3zHSNfezFNjUJt1HbSXn3qUMzeKc0=";
 733     })
 734   ];
 735
 736   # ...
 737 }
 738 ```
 739
 740 Patches are fetched from `sources.debian.org`, and so must come from a
 741 package version that was uploaded to the Debian archive.  Packages may
 742 be removed from there once that specific version isn't in any suite
 743 anymore (stable, testing, unstable, etc.), so maintainers should use
 744 `copy-tarballs.pl` to archive the patch if it needs to be available
 745 longer-term.
 746
 747 [Debian revision number]: https://www.debian.org/doc/debian-policy/ch-controlfields.html#version
 748
 749
 750 ## `fetchsvn` {#fetchsvn}
 751
 752 Used with Subversion. Expects `url` to a Subversion directory, `rev`, and `hash`.
 753
 754 ## `fetchgit` {#fetchgit}
 755
 756 Used with Git. Expects `url` to a Git repo, `rev`, and `hash`. `rev` in this case can be full the git commit id (SHA1 hash) or a tag name like `refs/tags/v1.0`.
 757
 758 Additionally, the following optional arguments can be given: `fetchSubmodules = true` makes `fetchgit` also fetch the submodules of a repository. If `deepClone` is set to true, the entire repository is cloned as opposing to just creating a shallow clone. `deepClone = true` also implies `leaveDotGit = true` which means that the `.git` directory of the clone won't be removed after checkout.
 759
 760 If only parts of the repository are needed, `sparseCheckout` can be used. This will prevent git from fetching unnecessary blobs from server, see [git sparse-checkout](https://git-scm.com/docs/git-sparse-checkout) for more information:
 761
 762 ```nix
 763 { stdenv, fetchgit }:
 764
 765 stdenv.mkDerivation {
 766   name = "hello";
 767   src = fetchgit {
 768     url = "https://...";
 769     sparseCheckout = [
 770       "directory/to/be/included"
 771       "another/directory"
 772     ];
 773     hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
 774   };
 775 }
 776 ```
 777
 778 ## `fetchfossil` {#fetchfossil}
 779
 780 Used with Fossil. Expects `url` to a Fossil archive, `rev`, and `hash`.
 781
 782 ## `fetchcvs` {#fetchcvs}
 783
 784 Used with CVS. Expects `cvsRoot`, `tag`, and `hash`.
 785
 786 ## `fetchhg` {#fetchhg}
 787
 788 Used with Mercurial. Expects `url`, `rev`, and `hash`.
 789
 790 A number of fetcher functions wrap part of `fetchurl` and `fetchzip`. They are mainly convenience functions intended for commonly used destinations of source code in Nixpkgs. These wrapper fetchers are listed below.
 791
 792 ## `fetchFromGitea` {#fetchfromgitea}
 793
 794 `fetchFromGitea` expects five arguments. `domain` is the gitea server name. `owner` is a string corresponding to the Gitea user or organization that controls this repository. `repo` corresponds to the name of the software repository. These are located at the top of every Gitea HTML page as `owner`/`repo`. `rev` corresponds to the Git commit hash or tag (e.g `v1.0`) that will be downloaded from Git. Finally, `hash` corresponds to the hash of the extracted directory. Again, other hash algorithms are also available but `hash` is currently preferred.
 795
 796 ## `fetchFromGitHub` {#fetchfromgithub}
 797
 798 `fetchFromGitHub` expects four arguments. `owner` is a string corresponding to the GitHub user or organization that controls this repository. `repo` corresponds to the name of the software repository. These are located at the top of every GitHub HTML page as `owner`/`repo`. `rev` corresponds to the Git commit hash or tag (e.g `v1.0`) that will be downloaded from Git. Finally, `hash` corresponds to the hash of the extracted directory. Again, other hash algorithms are also available, but `hash` is currently preferred.
 799
 800 To use a different GitHub instance, use `githubBase` (defaults to `"github.com"`).
 801
 802 `fetchFromGitHub` uses `fetchzip` to download the source archive generated by GitHub for the specified revision. If `leaveDotGit`, `deepClone` or `fetchSubmodules` are set to `true`, `fetchFromGitHub` will use `fetchgit` instead. Refer to its section for documentation of these options.
 803
 804 ## `fetchFromGitLab` {#fetchfromgitlab}
 805
 806 This is used with GitLab repositories. It behaves similarly to `fetchFromGitHub`, and expects `owner`, `repo`, `rev`, and `hash`.
 807
 808 To use a specific GitLab instance, use `domain` (defaults to `"gitlab.com"`).
 809
 810
 811 ## `fetchFromGitiles` {#fetchfromgitiles}
 812
 813 This is used with Gitiles repositories. The arguments expected are similar to `fetchgit`.
 814
 815 ## `fetchFromBitbucket` {#fetchfrombitbucket}
 816
 817 This is used with BitBucket repositories. The arguments expected are very similar to `fetchFromGitHub` above.
 818
 819 ## `fetchFromSavannah` {#fetchfromsavannah}
 820
 821 This is used with Savannah repositories. The arguments expected are very similar to `fetchFromGitHub` above.
 822
 823 ## `fetchFromRepoOrCz` {#fetchfromrepoorcz}
 824
 825 This is used with repo.or.cz repositories. The arguments expected are very similar to `fetchFromGitHub` above.
 826
 827 ## `fetchFromSourcehut` {#fetchfromsourcehut}
 828
 829 This is used with sourcehut repositories. Similar to `fetchFromGitHub` above,
 830 it expects `owner`, `repo`, `rev` and `hash`, but don't forget the tilde (~)
 831 in front of the username! Expected arguments also include `vc` ("git" (default)
 832 or "hg"), `domain` and `fetchSubmodules`.
 833
 834 If `fetchSubmodules` is `true`, `fetchFromSourcehut` uses `fetchgit`
 835 or `fetchhg` with `fetchSubmodules` or `fetchSubrepos` set to `true`,
 836 respectively. Otherwise, the fetcher uses `fetchzip`.
 837
 838 ## `requireFile` {#requirefile}
 839
 840 `requireFile` allows requesting files that cannot be fetched automatically, but whose content is known.
 841 This is a useful last-resort workaround for license restrictions that prohibit redistribution, or for downloads that are only accessible after authenticating interactively in a browser.
 842 If the requested file is present in the Nix store, the resulting derivation will not be built, because its expected output is already available.
 843 Otherwise, the builder will run, but fail with a message explaining to the user how to provide the file. The following code, for example:
 844
 845 ```nix
 846 requireFile {
 847   name = "jdk-${version}_linux-x64_bin.tar.gz";
 848   url = "https://www.oracle.com/java/technologies/javase-jdk11-downloads.html";
 849   hash = "sha256-lL00+F7jjT71nlKJ7HRQuUQ7kkxVYlZh//5msD8sjeI=";
 850 }
 851 ```
 852 results in this error message:
 853 ```
 854 ***
 855 Unfortunately, we cannot download file jdk-11.0.10_linux-x64_bin.tar.gz automatically.
 856 Please go to https://www.oracle.com/java/technologies/javase-jdk11-downloads.html to download it yourself, and add it to the Nix store
 857 using either
 858   nix-store --add-fixed sha256 jdk-11.0.10_linux-x64_bin.tar.gz
 859 or
 860   nix-prefetch-url --type sha256 file:///path/to/jdk-11.0.10_linux-x64_bin.tar.gz
 861
 862 ***
 863 ```
 864
 865 This function should only be used by non-redistributable software with an unfree license that we need to require the user to download manually.
 866 It produces packages that cannot be built automatically.
 867
 868 ## `fetchtorrent` {#fetchtorrent}
 869
 870 `fetchtorrent` expects two arguments. `url` which can either be a Magnet URI (Magnet Link) such as `magnet:?xt=urn:btih:dd8255ecdc7ca55fb0bbf81323d87062db1f6d1c` or an HTTP URL pointing to a `.torrent` file. It can also take a `config` argument which will craft a `settings.json` configuration file and give it to `transmission`, the underlying program that is performing the fetch. The available config options for `transmission` can be found [here](https://github.com/transmission/transmission/blob/main/docs/Editing-Configuration-Files.md#options)
 871
 872 ```nix
 873 { fetchtorrent }:
 874
 875 fetchtorrent {
 876   config = { peer-limit-global = 100; };
 877   url = "magnet:?xt=urn:btih:dd8255ecdc7ca55fb0bbf81323d87062db1f6d1c";
 878   hash = "";
 879 }
 880 ```
 881
 882 ### Parameters {#fetchtorrent-parameters}
 883
 884 - `url`: Magnet URI (Magnet Link) such as `magnet:?xt=urn:btih:dd8255ecdc7ca55fb0bbf81323d87062db1f6d1c` or an HTTP URL pointing to a `.torrent` file.
 885
 886 - `backend`: Which bittorrent program to use. Default: `"transmission"`. Valid values are `"rqbit"` or `"transmission"`. These are the two most suitable torrent clients for fetching in a fixed-output derivation at the time of writing, as they can be easily exited after usage. `rqbit` is written in Rust and has a smaller closure size than `transmission`, and the performance and peer discovery properties differs between these clients, requiring experimentation to decide upon which is the best.
 887
 888 - `config`: When using `transmission` as the `backend`, a json configuration can
 889   be supplied to transmission. Refer to the [upstream documentation](https://github.com/transmission/transmission/blob/main/docs/Editing-Configuration-Files.md) for information on how to configure.
 890