The following package shows a more compact way to create the same output generated in [](#ex-dockerTools-streamLayeredImage-hello).

```nix
{
  dockerTools,
  hello,
  lib,
}:
dockerTools.streamLayeredImage {
  name = "hello";
  tag = "latest";
  config.Cmd = [ "${lib.getExe hello}" ];
}
```
:::

[]{#ssec-pkgs-dockerTools-fetchFromRegistry}
## pullImage {#ssec-pkgs-dockerTools-pullImage}

This function is similar to the `docker image pull` command, which means it can be used to pull a Docker image from a registry that implements the [Docker Registry HTTP API V2](https://distribution.github.io/distribution/spec/api/).
By default, the `docker.io` registry is used.

The image will be downloaded as an uncompressed Docker-compatible repository tarball, which is suitable for use with other `dockerTools` functions such as [`buildImage`](#ssec-pkgs-dockerTools-buildImage), [`buildLayeredImage`](#ssec-pkgs-dockerTools-buildLayeredImage), and [`streamLayeredImage`](#ssec-pkgs-dockerTools-streamLayeredImage).

This function requires two different types of hashes/digests to be specified:

- One of them is used to identify a unique image within the registry (see the documentation for the `imageDigest` attribute).
- The other is used by Nix to ensure the contents of the output haven't changed (see the documentation for the `sha256` attribute).

Both hashes are required because they must uniquely identify some content in two completely different systems (the Docker registry and the Nix store), but their values will not be the same.
See [](#ex-dockerTools-pullImage-nixprefetchdocker) for a tool that can help gather these values.

### Inputs {#ssec-pkgs-dockerTools-pullImage-inputs}

`pullImage` expects a single argument with the following attributes:

`imageName` (String)

: Specifies the name of the image to be downloaded, as well as the registry endpoint.
  By default, the `docker.io` registry is used.
  To specify a different registry, prepend the endpoint to `imageName`, separated by a slash (`/`).
  See [](#ex-dockerTools-pullImage-differentregistry) for how to do that.

`imageDigest` (String)

: Specifies the digest of the image to be downloaded.

  :::{.tip}
  **Why can't I specify a tag to pull from, and have to use a digest instead?**

  Tags are often updated to point to different image contents.
  The most common example is the `latest` tag, which is usually updated whenever a newer image version is available.

  An image tag isn't enough to guarantee the contents of an image won't change, but a digest guarantees this.
  Providing a digest helps ensure that you will still be able to build the same Nix code and get the same output even if newer versions of an image are released.
  :::

`sha256` (String)

: The hash of the image after it is downloaded.
  Internally, this is passed to the [`outputHash`](https://nixos.org/manual/nix/stable/language/advanced-attributes#adv-attr-outputHash) attribute of the resulting derivation.
  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.