# Caching (/docs/template/caching)

<!-- agent-signals: reading_time_min: 3 · est_tokens: 1340 · updated: 2026-07-30 -->
Related: [Quickstart](/docs/template/quickstart.md), [How it works](/docs/template/how-it-works.md), [User and workdir](/docs/template/user-and-workdir.md), [Base image](/docs/template/base-image.md), [Private registries](/docs/template/private-registries.md), [Defining template](/docs/template/defining-template.md)

The caching concept is similar to [Docker's layer caching](https://docs.docker.com/build/cache/). For each layer command (`.copy()`, `.runCmd()`, `.setEnvs()`, etc.), we create a new layer on top of the existing.
Each layer is cached based on the command and its inputs (e.g., files copied, command executed, environment variables set).
If a layer command is unchanged and its inputs are the same as in any previous build, we reuse the cached layer instead of rebuilding it.

This significantly speeds up the build process, especially for large templates with many layers.
The cache is scoped to the project, so even if you have multiple templates, they can share the same cache if they have identical layers.

## Invalidation [#invalidation]

You can invalidate the caches only partially, or for the whole template.

### Partial [#partial]

Force rebuild from the next instruction, use the method:

<CodeGroup>
  <CodeBlockTabs defaultValue="JavaScript & TypeScript" groupId="javascript-typescript+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="JavaScript & TypeScript">
        JavaScript & TypeScript
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="JavaScript & TypeScript">
      ```typescript highlight={3}  
      const template = Template()
        .fromBaseImage()
        .skipCache()
        .runCmd("echo 'Hello, World!'")
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Python">
      ```python highlight={4}  
      template = (
          Template()
          .from_base_image()
          .skip_cache()
          .run_cmd("echo 'Hello, World!'")
      )
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

This will force rebuild from the next instruction, invalidating the cache for all subsequent instructions in the template.

### Whole template [#whole-template]

To force rebuild the whole template, you can use also `skipCache`/`skip_cache` parameter in the `Template.build` method:

<CodeGroup>
  <CodeBlockTabs defaultValue="JavaScript & TypeScript" groupId="javascript-typescript+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="JavaScript & TypeScript">
        JavaScript & TypeScript
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="JavaScript & TypeScript">
      ```typescript wrap highlight={2}  
      Template.build(template, 'my-template', {
        skipCache: true, // Configure cache skip (except for files)
      })
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Python">
      ```python wrap highlight={4}  
      Template.build(
          template,
          'my-template',
          skip_cache=True,  # Configure cache skip (except for files)
      )
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

This will skip the cache usage for the whole template build.

## Files caching [#files-caching]

When using the `.copy()` command, we cache the files based on their content. If the files haven't changed since the last build, we reuse them from the files cache.

We differ from Docker here. Because we build the template on our infrastructure, we use improved caching on files level.
Even if you invalidate the layer before `.copy()` (e.g., by changing ENV variables), we'll reuse the already uploaded files.
The `copy()` command will still be re-executed, but the files for the layer will be reused from the files cache, no need to upload them from your computer again.

To invalidate the cache for all subsequent instructions in the template **AND** the layer files cache, use the `forceUpload`/`force_upload` parameter.

<CodeGroup>
  <CodeBlockTabs defaultValue="JavaScript & TypeScript" groupId="javascript-typescript+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="JavaScript & TypeScript">
        JavaScript & TypeScript
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="JavaScript & TypeScript">
      ```typescript highlight={3}  
      const template = Template()
        .fromBaseImage()
        .copy("config.json", "/app/config.json", { forceUpload: true })
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Python">
      ```python highlight={4}  
      template = (
          Template()
          .from_base_image()
          .copy("config.json", "/app/config.json", force_upload=True)
      )
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

## Use case for caching [#use-case-for-caching]

You can leverage caching to create templates with multiple variants (e.g., different RAM or CPU) while reusing the common layers.
When building the template, just change the template name to a specific RAM/CPU configuration (e.g., `my-template-2cpu-2gb`, `my-template-1cpu-4gb`), keep the rest of the template definition the same, and the build process will reuse the cached layers.

## Optimize build times [#optimize-build-times]

To optimize build times, place frequently changing commands (e.g., copying source code) towards the end of your template definition. This way, earlier layers can be cached and reused more often.