Quick Start

The mambaorg/micromamba images contain only the programs from their parent image, the micromamba binary, bash, SSL certificates, and glibc. micromamba does not have a python dependency, and therefore the mambaorg/micromamba images do not contain python.

The micromamba images have an empty conda environment named base. Usually you will install software into this base environment.

1. Define your desired conda environment in a yaml file

   env.yaml

   name: base
   channels:
     - conda-forge
   dependencies:
     - pyopenssl=24.3.0
     - python=3.12.7
     - requests=2.32.3
   

   Warning

   Using an environment name other than base is not recommended! If you must use a different environment name, then read the documentation on multiple environments.

2. Copy the yaml file into your docker image and then pass the yaml file as a parameter to micromamba via the --file switch

   Dockerfile

   FROM mambaorg/micromamba:2.8.1
   
   COPY --chown=$MAMBA_USER:$MAMBA_USER env.yaml /tmp/env.yaml
   RUN micromamba install -y -n base -f /tmp/env.yaml && \
       micromamba clean --all --yes
   

3. Build your docker image

   $ docker build --quiet --tag my_app .
   sha256:b04d00cd5e7ab14f97217c24bc89f035db33a8d339bfb9857698d9390bc66cf8
   

   The base conda environment is automatically activated when the image is running.

   $ docker run -it --rm my_app python --version
   3.12.7
   

Running commands in Dockerfile within the conda environment

The conda environment is automatically activated for docker run ... commands, but it is not automatically activated during the build of an image (docker build ...). In order to use a RUN command to execute a program from a conda environment within a Dockerfile, as explained in detail in the next two subsections, you must:

1. Set ARG MAMBA_DOCKERFILE_ACTIVATE=1 to activate the conda environment

2. Use the ‘shell’ form of the RUN command

3. If using Podman to build the image, specify --format=docker in the podman build command

Activating a conda environment for RUN commands

No conda environment is automatically activated during the execution of RUN commands within a Dockerfile. To have an environment active during a RUN command, you must set ARG MAMBA_DOCKERFILE_ACTIVATE=1. For example:

FROM mambaorg/micromamba:2.8.1

COPY --chown=$MAMBA_USER:$MAMBA_USER env.yaml /tmp/env.yaml
RUN micromamba install --yes --file /tmp/env.yaml && \
    micromamba clean --all --yes
ARG MAMBA_DOCKERFILE_ACTIVATE=1  # (otherwise python will not be found)
RUN python -c 'import uuid; print(uuid.uuid4())' > /tmp/my_uuid

If you are using Podman to build the image, you must also specify the option --format=docker in the podman build command.

Use the shell form of RUN with micromamba

The Dockerfile RUN command can be invoked either in the ‘shell’ form:

RUN python -c "import uuid; print(uuid.uuid4())"

or the ‘exec’ form:

RUN ["python", "-c", "import uuid; print(uuid.uuid4())"]  # DO NOT USE THIS FORM!

You must use the ‘shell’ form of RUN or the command will not execute in the context of a conda environment.

Activating a conda environment for ENTRYPOINT commands

The Dockerfile for building the mambaorg/micromamba images contains:

ENTRYPOINT ["/usr/local/bin/_entrypoint.sh"]

where _entrypoint.sh activates the conda environment for any programs run via CMD in a Dockerfile or using docker run mambaorg/micromamba my_command on the command line. If you were to make an image derived from mambaorg/micromamba with:

ENTRYPOINT ["my_command"]

then you will have removed the conda activation from the ENTRYPOINT and my_command will be executed outside of any conda environment.

If you would like an ENTRYPOINT command to be executed within an active conda environment, then add "/usr/local/bin/_entrypoint.sh" as the first element of the JSON array argument to ENTRYPOINT. For example, if you would like for your ENTRYPOINT command to run python from a conda environment, then you would do:

ENTRYPOINT ["/usr/local/bin/_entrypoint.sh", "python"]