terraform-provider-docker/docs/resources/image.md

---
# generated by https://github.com/hashicorp/terraform-plugin-docs
page_title: "Resource docker_image - terraform-provider-docker"
subcategory: ""
description: |-
  Pulls a Docker image to a given Docker host from a Docker Registry.
   This resource will not pull new layers of the image automatically unless used in conjunction with dockerregistryimage registry_image.md data source to update the pull_triggers field.
---
<!-- Bug: Type and Name are switched -->
# Resource (docker_image)

Pulls a Docker image to a given Docker host from a Docker Registry.
 This resource will *not* pull new layers of the image automatically unless used in conjunction with [docker_registry_image](registry_image.md) data source to update the `pull_triggers` field.

## Example Usage

### Basic

Finds and downloads the latest `ubuntu:precise` image but does not check
for further updates of the image

```terraform
resource "docker_image" "ubuntu" {
  name = "ubuntu:precise"
}
```

### Dynamic updates

To be able to update an image dynamically when the `sha256` sum changes,
you need to use it in combination with `docker_registry_image` as follows:

```terraform
data "docker_registry_image" "ubuntu" {
  name = "ubuntu:precise"
}

resource "docker_image" "ubuntu" {
  name          = data.docker_registry_image.ubuntu.name
  pull_triggers = [data.docker_registry_image.ubuntu.sha256_digest]
}
```

### Build

You can also use the resource to build an image.
In this case the image "zoo" and "zoo:develop" are built.

```terraform
resource "docker_image" "zoo" {
  name = "zoo"
  build {
    path = "."
    tag  = ["zoo:develop"]
    build_arg = {
      foo : "zoo"
    }
    label = {
      author : "zoo"
    }
  }
}
```

You can use the `triggers` argument to specify when the image should be rebuild. This is for example helpful when you want to rebuild the docker image whenever the source code changes.

```terraform
resource "docker_image" "zoo" {
  name = "zoo"
  build {
    path = "."
  }
  triggers = {
    dir_sha1 = sha1(join("", [for f in fileset(path.module, "src/*") : filesha1(f)]))
  }
}
```

<!-- schema generated by tfplugindocs -->
## Schema

### Required

- `name` (String) The name of the Docker image, including any tags or SHA256 repo digests.

### Optional

- `build` (Block Set, Max: 1) Configuration to build an image. Please see [docker build command reference](https://docs.docker.com/engine/reference/commandline/build/#options) too. (see [below for nested schema](#nestedblock--build))
- `force_remove` (Boolean) If true, then the image is removed forcibly when the resource is destroyed.
- `keep_locally` (Boolean) If true, then the Docker image won't be deleted on destroy operation. If this is false, it will delete the image from the docker local storage on destroy operation.
- `platform` (String) The platform to use when pulling the image. Defaults to the platform of the current machine.
- `pull_trigger` (String, Deprecated) A value which cause an image pull when changed
- `pull_triggers` (Set of String) List of values which cause an image pull when changed. This is used to store the image digest from the registry when using the [docker_registry_image](../data-sources/registry_image.md).
- `triggers` (Map of String) A map of arbitrary strings that, when changed, will force the `docker_image` resource to be replaced. This can be used to rebuild an image when contents of source code folders change

### Read-Only

- `id` (String) Unique identifier for this resource. This is not the image ID, but the ID of the resource in the Terraform state. This is used to identify the resource in the Terraform state. To reference the correct image ID, use the `image_id` attribute.
- `image_id` (String) The ID of the image (as seen when executing `docker inspect` on the image). Can be used to reference the image via its ID in other resources.
- `latest` (String, Deprecated) The ID of the image in the form of `sha256:<hash>` image digest. Do not confuse it with the default `latest` tag.
- `output` (String, Deprecated)
- `repo_digest` (String) The image sha256 digest in the form of `repo[:tag]@sha256:<hash>`.

<a id="nestedblock--build"></a>
### Nested Schema for `build`

Required:

- `path` (String) Context path

Optional:

- `build_arg` (Map of String) Set build-time variables
- `dockerfile` (String) Name of the Dockerfile. Defaults to `Dockerfile`.
- `force_remove` (Boolean) Always remove intermediate containers
- `label` (Map of String) Set metadata for an image
- `no_cache` (Boolean) Do not use cache when building the image
- `remove` (Boolean) Remove intermediate containers after a successful build. Defaults to  `true`.
- `tag` (List of String) Name and optionally a tag in the 'name:tag' format
- `target` (String) Set the target build stage to build