How to Configure Python Environments with Conda or Mamba in LabNow AI Docker Images

LabNow AI Docker images use Mamba as a fast, drop-in replacement for Conda to bootstrap isolated Python environments, with optional system Python replacement for complete environment control.

The labnow-ai/lab-foundation repository provides a standardized, reproducible approach to provisioning Python environments in containerized AI workflows. By leveraging Conda's ecosystem with Mamba's parallel resolver, these Docker images achieve deterministic builds with dramatically reduced installation times.

Architecture Overview

The Python environment configuration follows a three-layer architecture defined in docker_atom/work/script-setup.sh and orchestrated by docker_base/Dockerfile. This design separates the base OS utilities from language runtimes, ensuring that Python packages remain isolated from system dependencies.

The build process coordinates two complementary tools:

• Conda – The full-featured package manager that handles channel management and environment creation
• Mamba – A C++ reimplementation that provides faster dependency resolution while maintaining Conda compatibility

Step-by-Step Configuration Process

Install Mamba for Fast Package Resolution

The build begins by installing the micromamba binary, a standalone, self-contained executable that provides Mamba functionality without a full Conda installation.

In docker_atom/work/script-setup.sh (lines 4-18), the setup_mamba() function downloads the binary to /opt/mamba, creates necessary directory structures, and symlinks the executable to /usr/bin/mamba:

# Simplified representation of setup_mamba implementation

setup_mamba() {
    local install_dir="/opt/mamba"
    local bin_dir="/usr/bin"
    
    # Download micromamba binary

    # Place in /opt/mamba

    # Symlink to /usr/bin/mamba for global access

}

This approach ensures that subsequent build steps can invoke mamba as a native package manager while keeping the installation footprint minimal.

Bootstrap Conda and Python

With Mamba available, the setup_conda_with_mamba() function (lines 61-67 in script-setup.sh) creates the Conda root prefix at /opt/conda and installs the requested Python version along with conda and pip.

This function accepts a PYTHON_VERSION argument (e.g., 3.12) and performs the following operations:

1. Creates the Conda prefix directory structure
2. Uses Mamba to install Python, conda, and pip into the prefix
3. Invokes setup_conda_postprocess() to configure channels and environment variables

The post-processing step (lines 22-59) configures Conda to use the conda-forge channel with strict priority, disables automatic updates, and writes activation scripts to /etc/profile.d/path-conda.sh to ensure the Conda Python appears first in PATH.

Replace the System Python (Optional)

The final configuration step, controlled by the SYS_PY_REPLACE environment variable, determines whether the container's system Python should be superseded by the Conda-managed installation.

In docker_base/Dockerfile (lines 9-45), conditional logic checks for existing system Python installations. When SYS_PY_REPLACE is set to true, the Dockerfile:

1. Removes or backs up the original system Python symlinks
2. Creates new symlinks pointing /usr/bin/python3 and /usr/bin/pip to the Conda equivalents in /opt/conda/bin/
3. Updates library paths to ensure shared objects resolve correctly

This ensures that any subsequent RUN commands using python or pip automatically utilize the Conda environment without requiring explicit path prefixes.

Key Environment Variables

The build process respects several environment variables that control Python environment configuration:

Variable	Purpose	Default Value
CONDA_PREFIX	Installation path for Conda root environment	/opt/conda
PYTHON_VERSION	Major.minor version of Python to install	3.12
SYS_PY_REPLACE	Whether to replace system Python with Conda Python	true

These variables are typically set via ARG or ENV directives in Dockerfiles or passed as build arguments during docker build.

Practical Configuration Examples

Building a Custom Image with Python 3.11

To create a LabNow AI image with a specific Python version, extend the base image and set the appropriate build arguments:

ARG BASE_NAMESPACE=labnow
ARG BASE_IMG="atom"
FROM ${BASE_NAMESPACE}/${BASE_IMG}

ARG SYS_PY_REPLACE="true"
ARG PYTHON_VERSION="3.11"

ENV CONDA_PREFIX=/opt/conda

RUN set -eux \
    && source /opt/utils/script-setup.sh \
    && export PATH=${CONDA_PREFIX}/bin:$PATH \
    && setup_mamba \
    && setup_conda_with_mamba ${PYTHON_VERSION} \
    && ln -sf "${CONDA_PREFIX}"/bin/python3.* /usr/bin/ \
    && ln -sf "${CONDA_PREFIX}"/bin/pip /usr/bin/

This pattern ensures that Mamba handles the heavy lifting of dependency resolution while Conda manages the environment structure.

Creating Additional Environments Inside Running Containers

Once the base image is running, users can create isolated project environments using either Conda or Mamba:

# Using Conda (traditional approach)

conda create -n datascience python=3.10 numpy pandas scikit-learn -y
conda activate datascience

# Using Mamba (faster resolution)

mamba create -n fastml python=3.12 pytorch torchvision -c pytorch -y
mamba activate fastml

Both commands respect the channel configuration established during the bootstrap process, defaulting to conda-forge with strict priority.

Summary

• LabNow AI Docker images utilize Mamba (micromamba) for rapid package resolution while maintaining full Conda compatibility for environment management.
• The configuration process follows three distinct phases: installing the Mamba binary, bootstrapping the Conda prefix with the desired Python version, and optionally replacing the system Python interpreter.
• Key implementation files include docker_atom/work/script-setup.sh (containing setup_mamba() and setup_conda_with_mamba()) and docker_base/Dockerfile (handling system Python replacement).
• Build customization is controlled through environment variables: PYTHON_VERSION, CONDA_PREFIX, and SYS_PY_REPLACE.

Frequently Asked Questions

What is the difference between using Conda and Mamba in LabNow AI images?

Mamba is a drop-in replacement for Conda written in C++ that provides significantly faster dependency resolution. In LabNow AI images, Mamba (specifically the micromamba binary) is used during the Docker build process to install Python and base packages quickly, while Conda remains available at runtime for environment management and channel operations. Both tools share the same package repository and environment structure.

How do I specify a different Python version when building a LabNow AI image?

Set the PYTHON_VERSION build argument to your desired major.minor version before the RUN command that invokes setup_conda_with_mamba(). For example, add ARG PYTHON_VERSION="3.11" in your Dockerfile. The setup_conda_with_mamba() function in docker_atom/work/script-setup.sh accepts this version string and installs the corresponding Python interpreter into the /opt/conda prefix using Mamba.

Can I keep the system Python while still using Conda in the container?

Yes, set SYS_PY_REPLACE to false during the build process. When this environment variable is set to false, the docker_base/Dockerfile logic skips the symlink replacement steps that would otherwise overwrite /usr/bin/python3 with the Conda-managed version. This allows the system Python to remain intact and accessible, while the Conda environment remains available at /opt/conda/bin/python.

Where are the Conda environments stored inside LabNow AI containers?

Conda environments are stored under the /opt/conda prefix by default. This location is defined by the CONDA_PREFIX environment variable set during the Docker build. The base environment containing the initially installed Python version resides directly in /opt/conda, while additional environments created with conda create or mamba create are stored in /opt/conda/envs/. The PATH is configured via /etc/profile.d/path-conda.sh to prioritize these locations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}