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

# Docker Images

export const CenteredImage = ({src, alt, width, caption, className}) => {
  const [basePath, setBasePath] = useState("");
  useEffect(() => {
    const path = window.location.pathname;
    setBasePath(path === "/docs" || path.startsWith("/docs/") ? "/docs" : "");
  }, []);
  return <Frame caption={caption} className={className} style={{
    maxWidth: width,
    marginInline: "auto"
  }}>
			<OptimizedImage src={`${basePath}${src}`} alt={alt} />
		</Frame>;
};

Whether you are building, pushing or pulling Docker images - Namespace employs comprehensive optimizations to accelerate your work.

## Faster Docker image builds

Building Docker images can be one of the most time-consuming parts of your CI/CD pipeline.
[Namespace Docker Builders](/docs/solutions/docker-builders) offer high-performance cold builds, and come with maximum caching builtin - no additional setup required.

### From Namespace Runners

If your GitHub Actions [run on Namespace](/docs/solutions/github-actions), Remote Builders are [enabled by default](/docs/solutions/github-actions/docker-builds) and will immediately accelerate your builds.

```yaml {3,6} theme={null}
jobs:
  build:
    runs-on: namespace-profile-default # was: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        # No docker/setup-buildx-action or docker/setup-qemu-action required!
      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: my-registry/my-app:latest
```

**Note**: If your workflow uses `docker/setup-buildx-action`, you need to [remove or replace](/docs/solutions/github-actions/docker-builds#skip-setup-buildx) it.

That's it! Your builds are now running on high-performance Remote Builders with advanced caching.

### From anywhere

<Steps titleSize="h3">
  <Step id="initialize-access-to-namespace" title={<span>Initialize access to Namespace</span>}>
    Using the [CLI](/docs/reference/cli/installation), log into your workspace.
    If you're accessing Namespace from a cloud provider or your CI platform, we recommend to set up [workflow federation](/docs/federation) instead.

    ```bash theme={null}
    nsc login
    ```
  </Step>

  <Step id="configure-your-docker" title={<span>Configure your Docker</span>}>
    Connect your local Docker CLI to use Namespace Builders for any build invocation.

    ```bash theme={null}
    nsc docker buildx setup --background --use
    ```

    The command above registers Namespace as a remote driver with your local Docker.
  </Step>

  <Step id="done" title={<span>Done!</span>}>
    Your builds will now run on Namespace:

    ```bash theme={null}
    docker build . -t app:latest
    ```
  </Step>
</Steps>

## Caching image pulls

Container Image caching allows you to dramatically reduce container startup times.
When enabling this feature, both image layers and the often expensive unpacking are cached locally.
Container image caching is available for any compute instance running on Namespace.

### From GitHub Actions

When running your GitHub Actions on [Namespace runners](/docs/solutions/github-actions), cached image pulls are available directly from the UI.

<Steps titleSize="h3">
  <Step id="faster-pulls-with-one-click" title={<span>Faster pulls with one click</span>}>
    To enable container image caching, simply check the corresponding option in your [runner profile configuration](https://cloud.namespace.so/workspace/actions/profiles).

    <CenteredImage width={600} alt="profile container image caching" src="/docs/images/github-actions/runnerprofilecontainerimages.png" />

    That's it!
    Repeated pulls of the same image will now complete in seconds rather than minutes.
  </Step>
</Steps>

### In-Network Registry Caching

Namespace maintains a transparent, in-network cache for public container registries, significantly improving pull performance for commonly used images.
Popular base images and frequently accessed containers are pre-cached within our network infrastructure, reducing pull times and eliminating redundant downloads across the internet.
This cache is automatically updated and managed to ensure you always receive the latest versions when needed.

## Private Image Registry

Private images using the [Namespace Container Registry](/docs/architecture/storage/container-registry) (nscr.io) are automatically distributed and cached throughout Namespace's network infrastructure reducing image pulls latency.

Using the [CLI](/docs/reference/cli/installation), you can configure access to nscr.io.

<Steps titleSize="h3">
  <Step id="configure-your-docker-2" title="Configure your Docker">
    ```bash theme={null}
    nsc docker login
    ```

    The command above will update your local Docker configuration and print your container registry address (e.g. `nscr.io/8enum0hp1l5ii`).
    If you want to obtain the address without updating your Docker configuration, run [`nsc workspace describe`](/docs/reference/cli/workspace-describe).
  </Step>

  <Step title="Build and push">
    ```bash theme={null}
    docker build . -t nscr.io/8enum0hp1l5ii/app:latest --push
    ```
  </Step>
</Steps>