---
# 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.
- `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) The ID of this resource.
- `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