This is needed to provide a guarantee to Nix that the contents of the image haven't changed, because Nix doesn't support the value in `imageDigest`.

`finalImageName` (String; _optional_)

: Specifies the name that will be used for the image after it has been downloaded.
  This only applies after the image is downloaded, and is not used to identify the image to be downloaded in the registry.
  Use `imageName` for that instead.

  _Default value:_ the same value specified in `imageName`.

`finalImageTag` (String; _optional_)

: Specifies the tag that will be used for the image after it has been downloaded.
  This only applies after the image is downloaded, and is not used to identify the image to be downloaded in the registry.

  _Default value:_ `"latest"`.

`os` (String; _optional_)

: Specifies the operating system of the image to pull.
  If specified, its value should follow the [OCI Image Configuration Specification](https://github.com/opencontainers/image-spec/blob/main/config.md#properties), which should still be compatible with Docker.
  According to the linked specification, all possible values for `$GOOS` in [the Go docs](https://go.dev/doc/install/source#environment) should be valid, but will commonly be one of `darwin` or `linux`.

  _Default value:_ `"linux"`.

`arch` (String; _optional_)

: Specifies the architecture of the image to pull.
  If specified, its value should follow the [OCI Image Configuration Specification](https://github.com/opencontainers/image-spec/blob/main/config.md#properties), which should still be compatible with Docker.
  According to the linked specification, all possible values for `$GOARCH` in [the Go docs](https://go.dev/doc/install/source#environment) should be valid, but will commonly be one of `386`, `amd64`, `arm`, or `arm64`.

  _Default value:_ the same value from `pkgs.go.GOARCH`.

`tlsVerify` (Boolean; _optional_)

: Used to enable or disable HTTPS and TLS certificate verification when communicating with the chosen Docker registry.
  Setting this to `false` will make `pullImage` connect to the registry through HTTP.

  _Default value:_ `true`.

`name` (String; _optional_)

: The name used for the output in the Nix store path.

  _Default value:_ a value derived from `finalImageName` and `finalImageTag`, with some symbols replaced.
  It is recommended to treat the default as an opaque value.

### Examples {#ssec-pkgs-dockerTools-pullImage-examples}

::: {.example #ex-dockerTools-pullImage-niximage}
# Pulling the nixos/nix Docker image from the default registry

This example pulls the [`nixos/nix` image](https://hub.docker.com/r/nixos/nix) and saves it in the Nix store.

```nix
{ dockerTools }:
dockerTools.pullImage {
  imageName = "nixos/nix";
  imageDigest = "sha256:b8ea88f763f33dfda2317b55eeda3b1a4006692ee29e60ee54ccf6d07348c598";
  finalImageName = "nix";
  finalImageTag = "2.19.3";
  hash = "sha256-zRwlQs1FiKrvHPaf8vWOR/Tlp1C5eLn1d9pE4BZg3oA=";
}
```
:::

::: {.example #ex-dockerTools-pullImage-differentregistry}
# Pulling the nixos/nix Docker image from a specific registry

This example pulls the [`coreos/etcd` image](https://quay.io/repository/coreos/etcd) from the `quay.io` registry.

```nix
{ dockerTools }:
dockerTools.pullImage {
  imageName = "quay.io/coreos/etcd";
  imageDigest = "sha256:24a23053f29266fb2731ebea27f915bb0fb2ae1ea87d42d890fe4e44f2e27c5d";
  finalImageName = "etcd";
  finalImageTag = "v3.5.11";
  hash = "sha256-Myw+85f2/EVRyMB3axECdmQ5eh9p1q77FWYKy8YpRWU=";
}
```
:::

::: {.example #ex-dockerTools-pullImage-nixprefetchdocker}
# Finding the digest and hash values to use for `dockerTools.pullImage`

Since [`dockerTools.pullImage`](#ssec-pkgs-dockerTools-pullImage) requires two different hashes, one can run the `nix-prefetch-docker` tool to find out the values for the hashes.
The tool outputs some text for an attribute set which you can pass directly to `pullImage`.

```shell
$ nix run nixpkgs#nix-prefetch-docker -- --image-name nixos/nix --image-tag 2.19.3 --arch amd64 --os linux