> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Caching

> Template build caching and optimization in HopX. Optimize template loading with caching strategies, reduce sandbox creation time, and manage template cache for improved performance. Learn how caching works, when to clear cache, and best practices for template optimization. Includes caching examples and performance tips.

Optimize template builds with caching strategies. Template caching speeds up builds by reusing layers and steps that haven't changed.

## Overview

Template caching helps you:

* Speed up template builds
* Reduce build costs
* Reuse unchanged layers
* Optimize build performance

<Note>
  Template builds use Docker layer caching. Steps that haven't changed are cached and reused, significantly speeding up rebuilds.
</Note>

## How Caching Works

Template builds cache each step:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai.template import Template

    template = Template()
    template.from_python_image("3.11-slim")

    # These steps are cached if unchanged
    template.apt_install("curl", "git")      # Cached if packages unchanged
    template.pip_install("numpy", "pandas")  # Cached if packages unchanged
    template.set_env("DEBUG", "true")        # Cached if value unchanged

    # Only changed steps are rebuilt
    template.pip_install("matplotlib")       # Only this step rebuilds if added
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    // Conceptual example
    const template = new Template('python:3.11-slim');

    // These steps are cached if unchanged
    template.aptInstall('curl', 'git');      // Cached if packages unchanged
    template.pipInstall('numpy', 'pandas');  // Cached if packages unchanged
    template.setEnv('DEBUG', 'true');        // Cached if value unchanged

    // Only changed steps are rebuilt
    template.pipInstall('matplotlib');       // Only this step rebuilds if added
    ```
  </Tab>
</Tabs>

## Skip Cache for Steps

Skip caching for specific steps:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai.template import Template

    template = Template()
    template.from_python_image("3.11-slim")

    # Install packages (cached)
    template.pip_install("numpy", "pandas")

    # Run command that should always execute (skip cache)
    template.run_cmd("git clone https://github.com/user/repo.git /app")
    template.skip_cache()  # Skip cache for previous step

    # Next steps are cached again
    template.pip_install("flask")
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    // Conceptual example
    const template = new Template('python:3.11-slim');

    // Install packages (cached)
    template.pipInstall('numpy', 'pandas');

    // Run command that should always execute (skip cache)
    template.runCmd('git clone https://github.com/user/repo.git /app');
    template.skipCache();  // Skip cache for previous step

    // Next steps are cached again
    template.pipInstall('flask');
    ```
  </Tab>
</Tabs>

## Skip Cache for Entire Build

Skip all caching for a build:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai.template import BuildOptions
    import os

    # Skip all caching
    options = BuildOptions(
        name="my-template",
        api_key=os.getenv("HOPX_API_KEY"),
        skip_cache=True  # Skip all caching
    )

    # Useful for:
    # - Debugging build issues
    # - Ensuring fresh builds
    # - Testing build steps
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    // Conceptual example
    const options = new BuildOptions({
      name: 'my-template',
      apiKey: process.env.HOPX_API_KEY,
      skipCache: true  // Skip all caching
    });
    ```
  </Tab>
</Tabs>

## Optimizing Build Order

Order steps for optimal caching:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai.template import Template

    template = Template()
    template.from_python_image("3.11-slim")

    # ✅ Good: Stable steps first (cached longer)
    template.apt_install("curl", "git")           # Rarely changes
    template.pip_install("numpy", "pandas")        # Changes less frequently
    template.set_env("NODE_ENV", "production")    # Rarely changes

    # ✅ Good: Frequently changing steps last
    template.run_cmd("git clone repo /app")       # Changes often
    template.run_cmd("cp config.json /app")       # Changes often

    # ❌ Bad: Frequently changing steps first
    # template.run_cmd("git clone repo /app")     # Invalidates all cache
    # template.apt_install("curl")                # Never cached
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    // Conceptual example
    const template = new Template('python:3.11-slim');

    // ✅ Good: Stable steps first (cached longer)
    template.aptInstall('curl', 'git');           // Rarely changes
    template.pipInstall('numpy', 'pandas');       // Changes less frequently
    template.setEnv('NODE_ENV', 'production');   // Rarely changes

    // ✅ Good: Frequently changing steps last
    template.runCmd('git clone repo /app');       // Changes often
    template.runCmd('cp config.json /app');       // Changes often
    ```
  </Tab>
</Tabs>

## Cache Invalidation

Understand when cache is invalidated:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai.template import Template

    template = Template()
    template.from_python_image("3.11-slim")

    # Cache is invalidated when:
    # 1. Step arguments change
    template.pip_install("numpy", "pandas")  # Cached
    template.pip_install("numpy", "pandas", "matplotlib")  # Cache invalidated

    # 2. Step order changes
    template.apt_install("curl")
    template.pip_install("numpy")
    # vs
    template.pip_install("numpy")
    template.apt_install("curl")  # Different cache key

    # 3. Base image changes
    template = create_template("python:3.11-slim")  # One cache
    template = create_template("python:3.12-slim")  # Different cache

    # 4. Files change (for COPY steps)
    # template.copy("/local/src", "/app")  # Cache invalidated if files change
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    // Conceptual example
    const template = new Template('python:3.11-slim');

    // Cache is invalidated when:
    // 1. Step arguments change
    template.pipInstall('numpy', 'pandas');  // Cached
    template.pipInstall('numpy', 'pandas', 'matplotlib');  // Cache invalidated

    // 2. Step order changes
    template.aptInstall('curl');
    template.pipInstall('numpy');
    // vs
    template.pipInstall('numpy');
    template.aptInstall('curl');  // Different cache key

    // 3. Base image changes
    const template1 = new Template('python:3.11-slim');  // One cache
    const template2 = new Template('python:3.12-slim');  // Different cache
    ```
  </Tab>
</Tabs>

## Best Practices

<Steps>
  <Step title="1. Order Steps by Stability">
    Place stable steps (system packages, language packages) before frequently changing steps (file copies, git clones).
  </Step>

  <Step title="2. Group Related Steps">
    Group related steps together to maximize cache hits.
  </Step>

  <Step title="3. Use skip_cache Sparingly">
    Only skip cache for steps that must always execute (e.g., git clones with latest changes).
  </Step>

  <Step title="4. Minimize Changes">
    Minimize changes to early steps to preserve cache for later steps.
  </Step>

  <Step title="5. Test Cache Behavior">
    Test builds to understand cache behavior and optimize step ordering.
  </Step>
</Steps>

## Related

* **[Building Templates](/core-concepts/templates/building)** - Create templates with caching
* **[Template Configuration](/core-concepts/templates/configuration)** - Configure template resources
* **[Getting Template Details](/core-concepts/templates/getting-details)** - View template information
* [CLI Template Commands](/cli/commands/template) - Template management from CLI

## Next Steps

* Learn about [Building Templates](/core-concepts/templates/building) to create templates
* Explore [Template Configuration](/core-concepts/templates/configuration) for advanced setup
* Review [Listing Templates](/core-concepts/templates/listing) to see your templates