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.
_Default value:_ `[]`.
`curlOpts` (String; _optional_)
: If specified, this value will be appended to the invocation of {manpage}`curl(1)` when downloading the URL(s) given to `fetchurl`.
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.
See `curlOptsList` for a way to pass values with whitespaces in them.
_Default value:_ `""`.
`curlOptsList` (List of String; _optional_)
: 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`.
This allows passing values that contain spaces, with no escaping needed.
_Default value:_ `[]`.
`showURLs` (Boolean; _optional_)
: If set to `true`, this will stop `fetchurl` from downloading anything at all.
Instead, it will output a list of all the URLs it would've used to download the content (after resolving `mirror://` URLs, for example).
This is useful for debugging.
_Default value:_ `false`.
`meta` (Attribute Set; _optional_)
: Specifies any [meta-attributes](#chap-meta) for the derivation returned by `fetchurl`.
_Default value:_ `{}`.
`passthru` (Attribute Set; _optional_)
: Specifies any extra [`passthru`](#chap-passthru) attributes for the derivation returned by `fetchurl`.
Note that `fetchurl` defines [`passthru` attributes of its own](#ssec-pkgs-fetchers-fetchurl-passthru-outputs).
Attributes specified in `passthru` can override the default attributes returned by `fetchurl`.
_Default value:_ `{}`.
`preferLocalBuild` (Boolean; _optional_)
: This is the same attribute as [defined in the Nix manual](https://nixos.org/manual/nix/stable/language/advanced-attributes.html#adv-attr-preferLocalBuild).
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.
_Default value:_ `true`.
`nativeBuildInputs` (List of Attribute Set; _optional_)
: Additional packages needed to download the content.
This is useful if you need extra packages for `postFetch` or `netrcPhase`, for example.
Has the same semantics as in [](#var-stdenv-nativeBuildInputs).
See [](#ex-fetchers-fetchurl-nixpkgs-version-postfetch) to understand how this can be used with `postFetch`.
_Default value:_ `[]`.
### Passthru outputs {#ssec-pkgs-fetchers-fetchurl-passthru-outputs}
`fetchurl` also defines its own [`passthru`](#chap-passthru) attributes:
`url` (String)
: The same `url` attribute passed in the argument to `fetchurl`.
### Examples {#ssec-pkgs-fetchers-fetchurl-examples}
:::{.example #ex-fetchers-fetchurl-nixpkgs-version}
# Using `fetchurl` to download a file
The following package downloads a small file from a URL and shows the most common way to use `fetchurl`:
```nix
{ fetchurl }:
fetchurl {
url = "https://raw.githubusercontent.com/NixOS/nixpkgs/23.11/.version";
hash = "sha256-BZqI7r0MNP29yGH5+yW2tjU9OOpOCEvwWKrWCv5CQ0I=";
}
```
After building the package, the file will be downloaded and place into the Nix store:
```shell
$ nix-build
(output removed for clarity)
/nix/store/4g9y3x851wqrvim4zcz5x2v3zivmsq8n-version
$ cat /nix/store/4g9y3x851wqrvim4zcz5x2v3zivmsq8n-version
23.11
```
:::
:::{.example #ex-fetchers-fetchurl-nixpkgs-version-multiple-urls}
# Using `fetchurl` to download a file with multiple possible URLs
The following package adapts [](#ex-fetchers-fetchurl-nixpkgs-version) to use multiple URLs.
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).