Fetchers

A Fetcher uses the Version selected by a Checker to obtain contents and a source Hash. The Version remains unchanged in the Pins File; rev or url mappings only change fetch arguments.

Common rules

• rev and url mappings must be Nix functions from a Version to a string.
• Do not mix target with its corresponding legacy fields.
• fetcherArgs supplies additional attributes to the Nixpkgs Fetcher. It cannot override target, version mapping, or hash fields managed by the tool.
• Do not supply hash manually. update computes it and the Reader injects it.

GitHub — pin.fetcher.github

Use target = "owner/repo" or owner and repo. rev defaults to version: version. Uses pkgs.fetchFromGitHub underneath.

{ pin }: {
  example = pin.mk {
    checker = pin.checker.cmd "printf '0.18.0'";
    fetcher = pin.fetcher.github {
      target = "NixOS/patchelf";
      rev = version: version;
    };
  };
}

fetcherArgs cannot override owner, repo, rev, or hash. If the version lacks a v prefix but upstream tags include one, use rev = version: "v${version}". Check upstream naming first.

Git — pin.fetcher.git

Use target or url. By default, rev uses the Version directly. Uses pkgs.fetchgit; configure options such as fetchSubmodules through fetcherArgs.

{ pin }: {
  example = pin.mk {
    checker = pin.checker.git { target = "https://github.com/NixOS/patchelf.git"; };
    fetcher = pin.fetcher.git {
      target = "https://github.com/NixOS/patchelf.git";
      fetcherArgs.fetchSubmodules = true;
    };
  };
}

Reserved fields are url, rev, and hash.

Hugging Face — pin.fetcher.huggingface

Use target or repoId for the repository identifier. By default, rev uses the Version directly. Uses pkgs.fetchFromHuggingFace, with lfs as the default backend. Your Nixpkgs must provide this Fetcher.

{ pin }: {
  model = pin.mk {
    checker = pin.checker.git {
      target = "https://huggingface.co/bert-base-uncased";
    };
    fetcher = pin.fetcher.huggingface { target = "bert-base-uncased"; };
  };
}

Repository contents may include large model weights. Check storage capacity and access requirements before downloading. Reserved fields are repoId, rev, tag, and hash.

File — pin.fetcher.url

Requires url = version: "..." and uses pkgs.fetchurl. target is an alias for the same field and also requires a mapping function. Keeps downloaded contents as a file without extracting them.

{ pin }: {
  example = pin.mk {
    checker = pin.checker.cmd "printf '0.18.0'";
    fetcher = pin.fetcher.url {
      url = version: "https://github.com/NixOS/patchelf/archive/refs/tags/${version}.tar.gz";
    };
  };
}

Archive — pin.fetcher.zip

Accepts the same fields as url and uses pkgs.fetchzip. Despite its name, it can also extract tar and other archives supported by Nixpkgs. The hash covers the extracted contents.

{ pin }: {
  example = pin.mk {
    checker = pin.checker.cmd "printf '0.18.0'";
    fetcher = pin.fetcher.zip {
      url = version: "https://github.com/NixOS/patchelf/archive/refs/tags/${version}.tar.gz";
      fetcherArgs.stripRoot = true;
    };
  };
}

Both url and zip reserve url and hash. Switching from a file Fetcher to an archive Fetcher changes the contents being hashed, so run update again.