Skip to main content
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:
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 developer reference documentation.
For CI/CD workflows, store your API key in your CI provider’s secrets storage (such as GitHub Actions secrets or GitLab CI/CD 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.

​
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 at the end shows the finished result.
The --mount=type=secret syntax used in this guide requires Docker 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.
1

Choose a base image

Anaconda provides several base 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:
FROM continuumio/miniconda3:v25.11.1-1 AS builder
2

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:
RUN conda install --name base \
  --channel https://repo.anaconda.cloud/repo/anaconda-tools \
  --override-channels \
  anaconda-registration
3

Define and install your dependencies

  1. Define your application’s dependencies in an environment.yml file and copy it into the image: 
    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: 
    RUN --mount=type=secret,id=ANACONDA_AUTH_API_KEY \
  conda env create \
  --prefix /env \
  --file environment.yml
    This expects a secret named ANACONDA_AUTH_API_KEY to be passed to docker build.
4

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:
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"]
The COPY and ENTRYPOINT values above are specific to this example. Adjust them to match your application’s files and start up command.
The final image contains only your runtime environment and application code—no conda installation, no base environment, no build tools.

​
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:
When you pass --secret id=ANACONDA_AUTH_API_KEY to docker build, Docker automatically looks for an environment variable of the same name.
docker build --secret id=ANACONDA_AUTH_API_KEY -t <IMAGE_NAME> .
Replace <IMAGE_NAME> with the name you want to give your Docker image.
The one-liner retrieves your key with anaconda auth api-key and passes it directly into the build.
For the full list of options for passing build secrets, see the Docker build secrets documentation.

​
Complete example

The following Dockerfile is based on the conda.Dockerfile example. 
# 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: 
docker build --secret id=ANACONDA_AUTH_API_KEY -t my-app .

​
Additional examples

The anaconda/docker-examples repository provides additional working examples, including conda-lock and .env file workflows. Contributions are welcome.