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

# Authenticated Docker builds

export const Comments = ({children}) => {
  return <div class="my-4 px-5 py-4 overflow-hidden rounded-2xl flex gap-3 border border-zinc-500/20 bg-zinc-50/50 dark:border-zinc-500/30 dark:bg-zinc-500/10" data-callout-type="comments">
      <div class="w-4">
        <svg width="14" height="14" viewBox="0 0 640 640" fill="currentColor" xmlns="http://www.w3.org/2000/svg" class="w-5 h-5" aria-label="Comments">
            <path d="M320 112C434.9 112 528 205.1 528 320C528 434.9 434.9 528 320 528C205.1 528 112 434.9 112 320C112 205.1 205.1 112 320 112zM320 576C461.4 576 576 461.4 576 320C576 178.6 461.4 64 320 64C178.6 64 64 178.6 64 320C64 461.4 178.6 576 320 576zM280 400C266.7 400 256 410.7 256 424C256 437.3 266.7 448 280 448L360 448C373.3 448 384 437.3 384 424C384 410.7 373.3 400 360 400L352 400L352 312C352 298.7 341.3 288 328 288L280 288C266.7 288 256 298.7 256 312C256 325.3 266.7 336 280 336L304 336L304 400L280 400zM320 256C337.7 256 352 241.7 352 224C352 206.3 337.7 192 320 192C302.3 192 288 206.3 288 224C288 241.7 302.3 256 320 256z" />
        </svg>
      </div>
      <div class="text-sm prose min-w-0 w-full">
        {children}
      </div>
    </div>;
};

If your Docker build pulls packages from Anaconda channels that require authentication, the build will fail unless the conda client inside the image can authenticate. However, including credentials in a Docker build introduces risk—secrets can leak into image layers or get committed to version control if not handled properly.

This guide shows you how to write a Dockerfile that authenticates to Anaconda channels using secure build secrets, keeping your credentials out of the final image.

## Authentication and API keys

Pulling packages from authenticated Anaconda channels requires an API key—a long-lived, scoped token tied to your Anaconda account that grants read access to the channels that are available to you.

You can obtain an API key using either of the following methods:

<Tabs>
  <Tab title="CLI">
    Running `anaconda login` automatically generates an API key for you to authenticate your conda client for automated build systems.

    View the API key by running `anaconda auth api-key`. For more information, see the [anaconda-auth](/cli-reference/anaconda-auth/getting-started) developer reference documentation.
  </Tab>

  <Tab title="Web UI">
    Create an API key from **Account Settings** in Anaconda Platform (Cloud). For more information, see [API keys](/anaconda-platform/cloud/user/api-keys).
  </Tab>
</Tabs>

<Warning>
  For CI/CD workflows, store your API key in your CI provider's secrets storage (such as [GitHub Actions secrets](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) or [GitLab CI/CD variables](https://docs.gitlab.com/ci/variables/)), expose it as the `ANACONDA_AUTH_API_KEY` environment variable in your workflow, and pass it to `docker build` with `--secret id=ANACONDA_AUTH_API_KEY`. Never hardcode secrets in Dockerfiles or commit them to version control.
</Warning>

## Writing the Dockerfile

The following steps walk through constructing a multi-stage Dockerfile that pulls packages from authenticated Anaconda channels and produces a minimal runtime image. Each step adds to the Dockerfile; the [complete example](#complete-example) at the end shows the finished result.

<Note>
  The `--mount=type=secret` syntax used in this guide requires [Docker BuildKit](https://docs.docker.com/build/buildkit/), which is the default build backend since Docker 23.0. If you are using an older version of Docker, you might need to enable BuildKit by setting `DOCKER_BUILDKIT=1` before running `docker build`.
</Note>

<Steps>
  <Step title="Choose a base image">
    Anaconda provides several [base Docker images](https://github.com/anaconda/docker-images) for you to use as starting points.

    Begin the Dockerfile by specifying a base image with conda pre-installed. Pin it to a specific version and assign it an alias so it can be referenced later in the Dockerfile:

    ```dockerfile theme={null}
    FROM continuumio/miniconda3:v25.11.1-1 AS builder
    ```
  </Step>

  <Step title="Install authentication support">
    To authenticate to Anaconda channels during the build, install the `anaconda-registration` package. This package provides plugins that automatically read Docker build secrets and pass them as authentication headers to the repository backend.

    Install it into the image's `base` environment before running any conda commands that require authentication:

    ```dockerfile theme={null}
    RUN conda install --name base \
      --channel https://repo.anaconda.cloud/repo/anaconda-tools \
      --override-channels \
      anaconda-registration
    ```
  </Step>

  <Step title="Define and install your dependencies">
    1. Define your application's dependencies in an [environment.yml file](/getting-started/working-with-conda/environments#creating-an-environment) and copy it into the image:

       ```dockerfile theme={null}
       COPY ./environment.yml ./environment.yml
       ```

    2. Mount your API key as a build secret and create the environment. The mount syntax depends on how you plan to pass the secret when you [build the image](#building-the-image):

           <Tabs>
             <Tab title="Environment variable">
               ```dockerfile theme={null}
               RUN --mount=type=secret,id=ANACONDA_AUTH_API_KEY \
                 conda env create \
                 --prefix /env \
                 --file environment.yml
               ```

               <Note>
                 This expects a secret named `ANACONDA_AUTH_API_KEY` to be passed to `docker build`.
               </Note>
             </Tab>

             <Tab title=".env file">
               If you prefer to store your API key in a file, mount it with `target=.env` as follows:

               ```dockerfile theme={null}
               RUN --mount=type=secret,id=dotenv,target=.env \
                 conda env create \
                 --prefix /env \
                 --file environment.yml
               ```

               <Note>
                 This expects a secret named `dotenv` pointing to a file that contains `ANACONDA_AUTH_API_KEY=<YOUR_API_KEY>`.
               </Note>
             </Tab>
           </Tabs>
  </Step>

  <Step title="Configure the runtime image">
    At this point, the Dockerfile produces an image with two conda environments: `base` (from the Miniconda image) and your custom runtime at `/env`. Shipping `base` is unnecessary and inflates the final image size.

    Adding a second stage to the Dockerfile solves this. Start from a minimal base image, copy only the runtime environment from the build stage, and then configure the entrypoint:

    ```dockerfile theme={null}
    FROM debian:13.3-slim

    COPY --from=builder /env /env
    ENV PATH="/env/bin:${PATH}"

    WORKDIR /app
    COPY app.py ./

    EXPOSE 8000
    ENTRYPOINT ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]
    ```

    <Note>
      The `COPY` and `ENTRYPOINT` values above are specific to this example. Adjust them to match your application's files and start up command.
    </Note>

    The final image contains only your runtime environment and application code—no conda installation, no `base` environment, no build tools.
  </Step>
</Steps>

## Building the image

With the Dockerfile written, build the image by passing your API key as a build secret. The method here must match the secret mount syntax used in your Dockerfile:

<Tabs>
  <Tab title="Environment variable">
    When you pass `--secret id=ANACONDA_AUTH_API_KEY` to `docker build`, Docker automatically looks for an environment variable of the same name.

    <CodeGroup>
      ```sh Command theme={null}
      docker build --secret id=ANACONDA_AUTH_API_KEY -t <IMAGE_NAME> .
      ```

      ```sh One-liner (with CLI) theme={null}
      ANACONDA_AUTH_API_KEY=$(anaconda auth api-key) docker build --secret id=ANACONDA_AUTH_API_KEY -t <IMAGE_NAME> .
      ```
    </CodeGroup>

    <Comments>
      Replace \<IMAGE\_NAME> with the name you want to give your Docker image.
    </Comments>

    <Note>
      The one-liner retrieves your key with `anaconda auth api-key` and passes it directly into the build.
    </Note>
  </Tab>

  <Tab title=".env file">
    Create a file (for example, `docker.env`) containing your API key:

    ```dotenv theme={null}
    ANACONDA_AUTH_API_KEY=<YOUR_API_KEY>
    ```

    Then pass the file as a secret when building:

    ```sh theme={null}
    docker build --secret id=dotenv,src=./docker.env -t <IMAGE_NAME> .
    ```

    <Comments>
      Replace \<IMAGE\_NAME> with the name you want to give your Docker image.
    </Comments>
  </Tab>
</Tabs>

<Tip>
  For the full list of options for passing build secrets, see the [Docker build secrets documentation](https://docs.docker.com/build/building/secrets/).
</Tip>

## Complete example

The following Dockerfile is based on the [conda.Dockerfile](https://github.com/anaconda/docker-examples/blob/main/examples/conda.Dockerfile) example.

```dockerfile expandable theme={null}
# Create the runtime conda environment
FROM continuumio/miniconda3:v25.11.1-1 AS builder

COPY ./environment.yml ./environment.yml

# Install the registration plugin for authenticated channel access
RUN conda install --name base anaconda-registration \
  --channel https://repo.anaconda.cloud/repo/anaconda-tools \
  --override-channels

# Mount the API key as a build secret and create the runtime environment
RUN --mount=type=secret,id=ANACONDA_AUTH_API_KEY \
  conda env create \
  --prefix /env \
  --file environment.yml

# Copy the environment into a minimal base image
FROM debian:13.3-slim

COPY --from=builder /env /env
ENV PATH="/env/bin:${PATH}"

WORKDIR /app
COPY app.py ./

EXPOSE 8000
ENTRYPOINT ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]
```

Build the image by passing your API key as a build secret:

```sh theme={null}
docker build --secret id=ANACONDA_AUTH_API_KEY -t my-app .
```

## Additional examples

The [anaconda/docker-examples](https://github.com/anaconda/docker-examples) repository provides additional working examples, including conda-lock and `.env` file workflows. Contributions are welcome.