# Why is fetchTarball not mentioned in "Chapter 11. Fetchers" of the Nixpkgs manual?
**URL:** https://discourse.nixos.org/t/why-is-fetchtarball-not-mentioned-in-chapter-11-fetchers-of-the-nixpkgs-manual/15319
**Category:** Help
**Created:** [October 3, 2021, 3:34am UTC](https://discourse.nixos.org/t/why-is-fetchtarball-not-mentioned-in-chapter-11-fetchers-of-the-nixpkgs-manual/15319 "2021-10-03T03:34:19Z")
**Posts on this page:** 4
**Page:** 1
### Author:  [@toraritte](https://discourse.nixos.org/u/toraritte)
#### Post date: [October 3, 2021, 3:34am UTC](https://discourse.nixos.org/t/why-is-fetchtarball-not-mentioned-in-chapter-11-fetchers-of-the-nixpkgs-manual/15319/1 "2021-10-03T03:34:19Z")
Just curious whether this is by accident or for a reason. [Chapter 11. Fetchers](https://nixos.org/manual/nixpkgs/stable/#chap-pkgs-fetchers) in the Nixpkgs manual mentions
- `fetchurl`
- `fetchzip`
- `fetchpatch`
and has sections for
- `fetchsvn`
- `fetchgit`
- `fossil`
- `fetchcvs`
- `fetchhg`
- `fromGitHub`
- `fromGitLab`
- `fromGitiles`
- `fromBitbucket`
- `fromSavannah`
- `fromRepoOrCz`
- `fromSourcehut`
but `fetchTarball` is only documented in [15.5. Built-in Functions](https://nixos.org/manual/nix/stable/#ssec-builtins) in the Nix manual. This seems odd, but then again, there are probably a lot of other fetchers that I’ve never heard of.
---
### Author:  [@jtojnar](https://discourse.nixos.org/u/jtojnar)
#### Post date: [October 3, 2021, 5:05am UTC](https://discourse.nixos.org/t/why-is-fetchtarball-not-mentioned-in-chapter-11-fetchers-of-the-nixpkgs-manual/15319/2 "2021-10-03T05:05:58Z")
The reason is that `builtins.fetchTarball`, just like `builtins.fetchGit` and `builtins.fetchurl`, is not a fetcher but a built-in function (primop). (Yes, it is confusing that Nix imports many builtins into scope automatically.)
Fetchers are actually just functions that produce fixed-output derivations. They utilize various builders (build scripts) to achieve that. For example, `fetchurl` fetcher is defined in [`pkgs/build-support/fetchurl/default.nix`](https://github.com/NixOS/nixpkgs/blob/6a466069126a0cf4bbbbcf19d815debf5d36097e/pkgs/build-support/fetchurl/default.nix) and its builder is [next to it](https://github.com/NixOS/nixpkgs/blob/6a466069126a0cf4bbbbcf19d815debf5d36097e/pkgs/build-support/fetchurl/builder.sh).
The builtins (e.g. `builtins.fetchurl`) are defined in [Nix source code](https://github.com/NixOS/nix/blob/1359c2c19a06e3e8b4d59b4e8d1378324322b428/src/libexpr/primops/fetchTree.cc#L255-L258). One difference is that the built-in functions cause download during evaluation, which is bad for all sorts of reasons. Compare
```auto
nix-repl> builtins.fetchTarball { url = https://github.com/NixOS/nixpkgs/archive/nixos-20.09.tar.gz; sha256 = ""; }
[…starts downloading immediately, blocking your script, eventually returning a store path]
```
with
```auto
nix-repl> fetchzip { url = https://github.com/NixOS/nixpkgs/archive/nixos-20.09.tar.gz; sha256 = ""; }
«derivation /nix/store/x4r0sqgzkjm36lil5i4dkifgs5ipwkzr-source.drv»
```
The latter returns a derivation almost immediately, delaying the fetching (and extraction) to only when you build the derivation.
* * *
I agree that a brief mention of the fetching builtins (maybe just a link to the Nix manual) would make sense in the Nixpkgs manual.
* * *
Just for completeness, `builtins.fetchTarball` serves the same purpose as `fetchzip` – download an archive and then unpack it into store. Despite the name and docs, both support tarballs and zip files. (Nix uses libarchive, and `fetchzip` depends on `unzip` and has `gnutar` available from `stdenv`.)
* * *
To make the `fetchurl` even more confusing, there are few more objects with the same name:
`fetchurl` [depends on `stdenv`](https://github.com/NixOS/nixpkgs/blob/6a466069126a0cf4bbbbcf19d815debf5d36097e/pkgs/build-support/fetchurl/default.nix#L123), which in turn uses `fetchurl` to obtain sources of its various dependencies. For that reason, there is also a simpler [`fetchurlBoot` function](https://github.com/NixOS/nixpkgs/blob/6a466069126a0cf4bbbbcf19d815debf5d36097e/pkgs/build-support/fetchurl/boot.nix) that is used to bootstrap stdenv.
`fetchurlBoot` function invokes [`fetchurl.nix` file](https://github.com/NixOS/nix/blob/aade43ffca1071c7bc376cedfb4beca0eb181bab/src/libexpr/fetchurl.nix) from Nix, which creates a fixed output derivation directly without a stdenv. To be able to do that, it uses a special value for the builder attribute – `builtin:fetchurl` (no relation to the primops). When nix sees it during build, it uses [custom code](https://github.com/NixOS/nix/blob/7c90552879da4d1df99b50c85e94201981e60123/src/libstore/builtins/fetchurl.cc#L9) instead of executing the builder script as it would normally.
---
### Author:  [@toraritte](https://discourse.nixos.org/u/toraritte)
#### Post date: [October 3, 2021, 2:40pm UTC](https://discourse.nixos.org/t/why-is-fetchtarball-not-mentioned-in-chapter-11-fetchers-of-the-nixpkgs-manual/15319/3 "2021-10-03T14:40:47Z")
> [@jtojnar](#):
>
> Just for completion, `builtins.fetchTarball` serves the same purpose as `fetchzip` – download an archive and then unpack it into store. Despite the name and docs, both support tarballs and zip files. (Nix uses libarchive, and `fetchzip` depends on `unzip` and uses `gnutar` from `stdenv` .)
What’s more confusing is that `fetchurl` also takes tarballs (e.g., see [example in the Nix manual](https://nixos.org/manual/nix/stable/#sec-expression-syntax)).
* * *
Anyway, appreciate the write-up, and it seems to be most comprehensive summary of fetchers. Thank you for taking the time!
* * *
Related threads:
- [Difference between fetchtarball fetchfromgithub fetchgit?](https://discourse.nixos.org/t/difference-between-fetchtarball-fetchfromgithub-fetchgit/3279)
- [Difference between `fetchgit` and `fetchGit`](https://discourse.nixos.org/t/difference-between-fetchgit-and-fetchgit/3619)
- [Troubleshooting fetch\* commands (like fetchFromGitHub)](https://discourse.nixos.org/t/troubleshooting-fetch-commands-like-fetchfromgithub/6159)
- [Deceptive scope mismatches](https://discourse.nixos.org/t/deceptive-scope-mismatches/9239)
- [Why wouldn’t the sha256 hash change when fetching from a different URL (when updating a package)?](https://discourse.nixos.org/t/why-wouldnt-the-sha256-hash-change-when-fetching-from-a-different-url-when-updating-a-package/11745)
---
### Author:  [@jtojnar](https://discourse.nixos.org/u/jtojnar)
#### Post date: [October 3, 2021, 3:14pm UTC](https://discourse.nixos.org/t/why-is-fetchtarball-not-mentioned-in-chapter-11-fetchers-of-the-nixpkgs-manual/15319/4 "2021-10-03T15:14:36Z")
> [@toraritte](#):
>
> What’s more confusing is that `fetchurl` also takes tarballs (e.g., see [example in the Nix manual](https://nixos.org/manual/nix/stable/#sec-expression-syntax)).
Yeah, the difference is what is produced. `fetchurl` will just save the tarball as is into the store, whereas `fetchzip`/`fetchTarball` will unpack it and store its contents. Perhaps a more precise name would be `fetchAndExtractArchive`.
You can use unextracted archives as `src` in `stdenv.mkDerivation` thanks to generic builder’s [`unpackPhase`](https://github.com/NixOS/nixpkgs/blob/0b672c78ab67e9611f66714a5016ce37bd19a4d4/pkgs/stdenv/generic/setup.sh#L888). In fact, `fetchzip` also [uses `unpackFile` internally](https://github.com/NixOS/nixpkgs/blob/0b672c78ab67e9611f66714a5016ce37bd19a4d4/pkgs/build-support/fetchzip/default.nix#L42) (although, manually, not through phases, since `fetchurl` replaces the builder for one that does not run `genericBuild`).