# pkgs.dockerTools {#sec-pkgs-dockerTools}

`pkgs.dockerTools` is a set of functions for creating and manipulating Docker images according to the [Docker Image Specification v1.3.0](https://github.com/moby/moby/blob/46f7ab808b9504d735d600e259ca0723f76fb164/image/spec/spec.md#image-json-field-descriptions).
Docker itself is not used to perform any of the operations done by these functions.

## buildImage {#ssec-pkgs-dockerTools-buildImage}

This function builds a Docker-compatible repository tarball containing a single image.
As such, the result is suitable for being loaded in Docker with `docker image load` (see [](#ex-dockerTools-buildImage) for how to do this).

This function will create a single layer for all files (and dependencies) that are specified in its argument.
Only new dependencies that are not already in the existing layers will be copied.
If you prefer to create multiple layers for the files and dependencies you want to add to the image, see [](#ssec-pkgs-dockerTools-buildLayeredImage) or [](#ssec-pkgs-dockerTools-streamLayeredImage) instead.

This function allows a script to be run during the layer generation process, allowing custom behaviour to affect the final results of the image (see the documentation of the `runAsRoot` and `extraCommands` attributes).

The resulting repository tarball will list a single image as specified by the `name` and `tag` attributes.
By default, that image will use a static creation date (see documentation for the `created` attribute).
This allows `buildImage` to produce reproducible images.

:::{.tip}
When running an image built with `buildImage`, you might encounter certain errors depending on what you included in the image, especially if you did not start with any base image.

If you encounter errors similar to `getProtocolByName: does not exist (no such protocol name: tcp)`, you may need to add the contents of `pkgs.iana-etc` in the `copyToRoot` attribute.
Similarly, if you encounter errors similar to `Error_Protocol ("certificate has unknown CA",True,UnknownCa)`, you may need to add the contents of `pkgs.cacert` in the `copyToRoot` attribute.
:::

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

`buildImage` expects an argument with the following attributes:

`name` (String)

: The name of the generated image.

`tag` (String or Null; _optional_)

: Tag of the generated image.
  If `null`, the hash of the nix derivation will be used as the tag.

  _Default value:_ `null`.

`fromImage` (Path or Null; _optional_)

: The repository tarball of an image to be used as the base for the generated image.
  It must be a valid Docker image, such as one exported by `docker image save`, or another image built with the `dockerTools` utility functions.
  This can be seen as an equivalent of `FROM fromImage` in a `Dockerfile`.
  A value of `null` can be seen as an equivalent of `FROM scratch`.

  If specified, the layer created by `buildImage` will be appended to the layers defined in the base image, resulting in an image with at least two layers (one or more layers from the base image, and the layer created by `buildImage`).
  Otherwise, the resulting image with contain the single layer created by `buildImage`.

  :::{.note}
  Only **Env** configuration is inherited from the base image.
  :::

  _Default value:_ `null`.

`fromImageName` (String or Null; _optional_)

: Used to specify the image within the repository tarball in case it contains multiple images.
  A value of `null` means that `buildImage` will use the first image available in the repository.

  :::{.note}
  This must be used with `fromImageTag`. Using only `fromImageName` without `fromImageTag` will make `buildImage` use the first image available in the repository.
  :::

  _Default value:_ `null`.

`fromImageTag` (String or Null; _optional_)

: Used to specify the image within the repository tarball in case it contains multiple images.
  A value of `null` means that `buildImage` will use the first image available in the repository.