# cache
<subtitle>How the caching process works</subtitle>

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

This greatly speeds up the building process, especially for large templates with many layers. The cache is scoped within the team, so even if you have multiple templates, they can share the same cache if they have the same layer.

## Cache invalidation

You can invalidate only part of the cache, or you can invalidate the entire template.

### Partially invalid

To force a rebuild starting from the next instruction, use the following method:

```python
template = (
    Template()
    .from_base_image()
    .skip_cache()
    .run_cmd("echo 'Hello, World!'")
)
```

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

### The entire template is invalid

To force a rebuild of the entire template, you can also use the `skip_cache` parameter in the `Template.build` method:

```python
Template.build(
    template,
    'my-template',
    skip_cache=True, # Configure cache skip (except files)
)
```

This will skip cache usage for the entire template build.

## File cache

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

We are different here with Docker. Because we build templates on our infrastructure, we use improved file-level caching. Even if you invalidate the layer before `.copy()` (for example, by changing an environment variable), we will reuse the uploaded file. The `copy()` command will still be re-executed, but the files for that layer will be reused from the file cache, eliminating the need to upload them from your computer again.

To invalidate all subsequent directives in the template as well as layer file caching, use the `force_upload` parameter.

```python
template = (
    Template()
    .from_base_image()
    .copy("config.json", "/app/config.json", force_upload=True)
)
```

## Caching use cases

You can leverage caching to create templates with multiple variations (for example, different RAM or CPU) while reusing common layers. When building a template, simply change the template name to the 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 time

To optimize build times, place frequently changed commands (for example, copy source code) at the end of the template definition. This way, earlier layers can be cached and reused more frequently.