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

> Configure Python environments in LabNow AI Docker images using Mamba, a fast Conda alternative. Gain complete control with optional system Python replacement for isolated environments.

- Repository: [LabNow.ai/lab-foundation](https://github.com/labnow-ai/lab-foundation)
- Tags: how-to-guide
- Published: 2026-03-05

---

**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`](https://github.com/labnow-ai/lab-foundation/blob/main/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`](https://github.com/labnow-ai/lab-foundation/blob/main/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`:

```bash

# 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`](https://github.com/labnow-ai/lab-foundation/blob/main/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`](https://github.com/labnow-ai/lab-foundation/blob/main//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:

```dockerfile
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:

```bash

# Using Conda (traditional approach)

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

```

```bash

# 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`](https://github.com/labnow-ai/lab-foundation/blob/main/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`](https://github.com/labnow-ai/lab-foundation/blob/main/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`](https://github.com/labnow-ai/lab-foundation/blob/main//etc/profile.d/path-conda.sh) to prioritize these locations.