---
url: /en/build/internal-steps/docker/cache.md
---
`docker:cache`

\==Docker Cache==, builds a Docker image as a cache for reuse in subsequent builds.

It helps avoid redundant downloads of network resources such as `dependencies`.

* [Applicable Events](#docker-cache-applicable-events)
* [Parameters](#docker-cache-parameters)
* [Output Results](#docker-cache-output)
* [Configuration Examples](#docker-cache-configuration-examples)

## Applicable Events {#docker-cache-applicable-events}

[All Events](../../trigger-rule.md#trigger-event)

## Parameters {#docker-cache-parameters}

The list below gives an overview of all parameters before you jump to a specific
section for details.

* [dockerfile](#docker-cache-parameters-dockerfile): Dockerfile path used to build the cache image
* [by](#docker-cache-parameters-by): Files the cache image build depends on; used to trigger a cache rebuild
* [versionBy](#docker-cache-parameters-versionBy): Files involved in cache version calculation; defaults to `by`
* [buildArgs](#docker-cache-parameters-buildArgs): Extra `--build-arg` arguments injected at build time
* [target](#docker-cache-parameters-target): Maps to `docker build --target`; build only a specific stage
* [sync](#docker-cache-parameters-sync): Sync mode; wait until the cache image push succeeds before continuing
* [ignoreBuildArgsInVersion](#docker-cache-parameters-ignoreBuildArgsInVersion):
  Whether to ignore `buildArgs` in version calculation

Detailed descriptions for each parameter are provided below.

### dockerfile {#docker-cache-parameters-dockerfile}

* type: `String`
* required: `true`

The path to the Dockerfile used to build the cache image.

To avoid excessively long build times,
the Docker image build timeout is controlled by the [job.timeout](../../grammar.md#job-timeout) parameter.

### by {#docker-cache-parameters-by}

* type: `Array<String>` | `String`
* required: `false`

Specifies the list of files that the cache image build process depends on.

The Docker build context (the files visible during `docker build`) contains only
the Dockerfile and the files declared in `by`. If the cache image build also needs
other files, list them in `by` as well; otherwise they are not copied into the build
context and are effectively unavailable during the build.

* Supports array format
* Supports string format, with multiple files separated by commas.

### versionBy {#docker-cache-parameters-versionBy}

* type: `Array<String>` | `String`
* required: `false`

Used for version control. If `versionBy` is not provided, it defaults to the value of `by`.

When the content of the file pointed to by `versionBy` changes, a new version is considered.
The calculation logic is based on the expression:

`sha1(Dockerfile + versionBy + buildArgs + target + arch)`

* Supports array format
* Supports string format, with multiple files separated by commas.

### buildArgs {#docker-cache-parameters-buildArgs}

* type: `Object`
* required: `false`

Inserts additional build arguments during build (`--build-arg $key=$value`). If the value is null,
only the key is added (`--build-arg $key`).

### target {#docker-cache-parameters-target}

* type: `String`
* required: `false`

Corresponds to the --target parameter in docker build,
allowing selective building of specific stages in the Dockerfile instead of the entire Dockerfile.

### sync {#docker-cache-parameters-sync}

* type: `Boolean`
* required: `false`
* default: `false`

Specifies whether to operate in synchronous mode. If `true`,
it waits for the cache image to be successfully pushed before proceeding with subsequent tasks.

### ignoreBuildArgsInVersion {#docker-cache-parameters-ignoreBuildArgsInVersion}

* type: `Boolean`
* required: `false`
* default: `false`

Specifies whether to ignore `buildArgs` in version calculation.

See [Version Control](#docker-cache-parameters-versionBy)

## Output Results {#docker-cache-output}

```javascript
{
  // The docker image name corresponding to the cache
  name;
}
```

## Configuration Examples {#docker-cache-configuration-examples}

```yaml title=".cnb.yml"
main:
  push:
    - docker:
        image: node:14
      stages:
        - name: build cache image
          type: docker:cache
          options:
            dockerfile: cache.dockerfile
            # by supports two formats: array, string
            by:
              - package.json
              - package-lock.json
            versionBy:
              - package-lock.json
          exports:
            name: DOCKER_CACHE_IMAGE_NAME
        - name: use cache
          image: $DOCKER_CACHE_IMAGE_NAME
          commands:
            - cp -r "$NODE_PATH" ./node_modules
        - name: build with cache
          script:
            - npm run build
```

Where `cache.dockerfile` is a Dockerfile used to build the cache image, for example:

```dockerfile
# Choose a Base image
FROM node:14

# Set working directory
WORKDIR /space

# Copy the file list from 'by'
COPY . .

# Install dependencies based on the copied files
RUN npm ci

# Set the required environment variables
ENV NODE_PATH=/space/node_modules
```