Micromamba Environments for Bioinformatics

Required route: Install and verify Micromamba if needed, read the channel policy, then jump to the small QC environment lab. That lab creates and checks one Python/FastQC/MultiQC environment. The other creation commands are alternative reference examples, not extra steps to run in sequence; several deliberately reuse qc-tools. You do not need the combined R/Python environment or any cleanup command to complete the required lab. If you came from Command Line Part 2, finish installation only, then return to its SeqKit checkpoint.

Why environment management matters in bioinformatics

Bioinformatics projects combine command-line programs, Python libraries, R packages, compiled dependencies, and reference-data utilities. These components often require different versions of shared libraries. Installing everything into a system Python or one shared environment makes it difficult to identify which project changed a dependency and can break an older analysis.

An environment is an isolated prefix containing an interpreter, packages, and their dependencies. It does not replace good scientific documentation: an environment file records software requirements, while the workflow should also record input data, reference versions, parameters, and results. The goal is to make the computational part of an analysis inspectable and repeatable on another machine.

Which tool should you use?

Micromamba: the current lightweight default

Micromamba is a self-contained, statically linked executable. It does not ship with a populated base environment. Instead, it stores environments and package caches below the MAMBA_ROOT_PREFIX, which makes it convenient on shared clusters, containers, and personal machines where you want a small installation. The official Mamba documentation currently identifies its automatic installer as the recommended Micromamba installation route.

Conda and Miniforge: useful alternatives

Conda remains a general package and environment manager with a large user base and extensive documentation. Miniforge is a small Conda distribution configured for the conda-forge ecosystem and is a practical choice when you want a traditional Conda installation with the familiar conda command. Choose one primary manager per machine or project. Do not initialize several competing base installations and then guess which executable is running.

Mamba 2: compatible terminology, different installation story

In Mamba 2, the mamba executable has the same user interface and experience as micromamba. Older tutorials that tell users to install the Python-based Mamba package into a Conda base environment are therefore not the best starting point for a new installation. Existing Mamba or Conda environments can still be useful, but new users should follow the current installation documentation for the selected tool.

Install Micromamba

The following route is documented for Linux, macOS, and Git Bash on Windows. It downloads and runs the official installer script over HTTPS, then initializes the selected shell. Review the script and follow local policy before running it on a managed or highly restricted system.

Linux, macOS, or Git Bash

# Install the current Micromamba executable using the official installer
"${SHELL}" <(curl -L micro.mamba.pm)

# Start a new shell after the installer finishes, or inspect the executable
micromamba --version

# Initialize Bash with an explicit root prefix
micromamba shell init -s bash -r "$HOME/micromamba"
source "$HOME/.bashrc"

# For Zsh, use these two commands instead:
# micromamba shell init -s zsh -r "$HOME/micromamba"
# source "$HOME/.zshrc"

If your institution does not allow shell scripts or the automatic installer, use the official manual-install instructions to download the platform-specific static executable. On a cluster, ask the administrator whether Micromamba is already available as a module before installing a private copy.

Windows PowerShell

# Official PowerShell installation route
Invoke-Expression ((Invoke-WebRequest -Uri https://micro.mamba.pm/install.ps1 -UseBasicParsing).Content)

# Initialize a user-owned root prefix
micromamba shell init -s powershell -r "$HOME\micromamba"
# Restart PowerShell, then verify
micromamba --version

Verify the installation and root prefix

micromamba info
micromamba --version

Check this output before troubleshooting: it reports the root prefix, environment directories, package cache, configuration files, and detected platform. The command examples below are documentation-based; package solving and installation depend on your operating system, channel metadata, and current package availability. No successful biological analysis follows from creating an environment.

Configure channels deliberately

Use the same explicit channel policy when creating or recreating an environment, and preserve channel intent in the authored specification and resolved export. For Bioconda packages, the documented order and strict priority matter; avoid mixing in additional channels casually.

A channel is a repository of package metadata and package archives. For many bioinformatics workflows, conda-forge provides general dependencies and bioconda provides many domain-specific tools. Channel configuration affects the solver, so keep it explicit and avoid mixing unrelated defaults without understanding the consequences.

For this lesson, keep channel choices on each command instead of changing a shared .condarc/.mambarc. Bioconda recommends conda-forge before bioconda on the command line (higher priority first) and strict priority. Each create command below therefore uses both --override-channels and --channel-priority strict: the first prevents configured default channels from silently joining the solve, while the second enforces the declared order. In particular, do not add Anaconda defaults implicitly.

micromamba create -n qc-tools \
  --override-channels -c conda-forge -c bioconda --channel-priority strict \
  fastqc multiqc

Include these options on every create command to make its channel selection independent of machine-level channel configuration. micromamba config list and micromamba info are useful for inspecting configured values, but --override-channels governs these invocations. Strict priority constrains solver choices; it cannot make unavailable packages or unsupported platforms work.

When a package cannot be solved, first check its availability, platform support, channel choice, and version constraints. Do not immediately add many channels or remove all version pins; that can create a solution that is difficult to reproduce.

Create, activate, and remove environments

Use one environment for one coherent workflow. Keep the base or root prefix small. The example below creates a Python environment for inspecting sequencing quality and reporting results.

# Create an environment with all initial requirements together
micromamba create -n qc-tools \
  --override-channels -c conda-forge -c bioconda --channel-priority strict \
  python=3.11 fastqc multiqc

# Activate it in the current shell
micromamba activate qc-tools

# Confirm which executable and Python are active
which python
python --version
which fastqc
fastqc --version

# List environments and leave the active environment
micromamba env list
micromamba deactivate

Installing the first group of packages together gives the solver more information than installing one package at a time. In a shared HPC environment, package installation may need to happen in a login shell while analysis jobs activate the same environment in their job script.

Use a project-local prefix when appropriate

A named environment is convenient for a personal workstation. A project-local prefix makes the environment location visible next to the project, which can be useful for a small reproducible example. It does not make the environment portable by itself; binaries still depend on the operating system and CPU architecture.

mkdir -p ~/projects/qc-demo
cd ~/projects/qc-demo
micromamba create -p ./env \
  --override-channels -c conda-forge -c bioconda --channel-priority strict \
  python=3.11 fastqc
micromamba activate ./env
micromamba deactivate

Optional cleanup after you finish

Cleanup is not required for the lab. Skip these removal commands while you still need the environment. Remove an environment only after checking that it is not referenced by a scheduled job or notebook kernel:

micromamba env remove -n qc-tools
# For a prefix environment:
# micromamba env remove -p ./env

Optional reference: combine Python, R, and command-line tools

Skip this section for the required QC lab. This larger single-cell environment can download substantial dependencies and is not needed for the Bash lessons, SeqKit setup or the authored YAML exercise. Continue at the small QC environment lab instead unless you deliberately want this separate, untested extension.

Prefer packages from the Conda-compatible channels when a suitable package exists. Use pip only for packages that are not available through the selected Conda channels, and install it after the compiled Conda dependencies. Record those pip requirements in the environment file.

micromamba create -n single-cell \
  --override-channels -c conda-forge -c bioconda --channel-priority strict \
  python=3.11 \
  scanpy anndata \
  r-base r-seurat \
  samtools bcftools multiqc

micromamba activate single-cell
python -c "import scanpy, anndata; print(scanpy.__version__, anndata.__version__)"
R --slave -e "cat(R.version.string, '\n')"
samtools --version | head -n 1

Do not assume that a package name is identical across ecosystems. For example, an R package may be named with an r- prefix and a Bioconductor package may use a bioconductor- prefix. Search the relevant channel and read the package recipe before adding it to a production environment.

Required lab: make a small QC environment reproducible

An environment file is a readable record of requested packages and channels. It is not a complete record of a scientific analysis, and a broad export can contain platform-specific build details. For teaching and cross-platform sharing, start with a small, intentional specification and test it on a clean environment.

Work in a project directory so the authored specification and later exports stay together. In Bash, create and enter a directory, then use the displayed here-document to write the exact YAML file; it does not install anything or prove that a solve will succeed.

mkdir -p ~/projects/qc-environment
cd ~/projects/qc-environment
pwd
cat > environment.yml <<'YAML'
name: qc-tools
channels:
  - conda-forge
  - bioconda
dependencies:
  - python=3.11
  - fastqc
  - multiqc
YAML

Before creating an environment, predict: which Python minor version is requested, and what do the two channel lines control? Then confirm pwd is your project directory and inspect exactly what you saved:

ls -l environment.yml
sed -n '1,20p' environment.yml

The YAML is an authored request, not evidence of a successful dependency solve or installation. It records direct package requests and channel intent; the solver still chooses compatible builds using current metadata for your platform.

1. If environment.yml is absent or malformed, stop and return to the save step before creating anything.
2. Create the named environment from the saved specification, explicitly retaining the documented channel order and strict priority:

   micromamba create -f environment.yml --override-channels -c conda-forge -c bioconda --channel-priority strict

   A successful solve/install ends without an error. If solving fails, stop and inspect the error, platform support, channels, and configuration rather than continuing with later commands.
3. Check that the environment exists and that both requested tools run:

   micromamba env list
   micromamba run -n qc-tools python --version
   micromamba run -n qc-tools fastqc --version
   micromamba run -n qc-tools multiqc --version

   The environment list should include qc-tools; the commands should print version information and return successfully. These checks establish that the commands are available, not that any biological data have been analyzed.
4. Export the resolved environment, keep the original as an audit record, and prepare a reviewed copy before recreating it under a distinct, unused name:

   micromamba env export -n qc-tools > environment-resolved.yml
   cp environment-resolved.yml environment-resolved-reviewed.yml
   sed -n '1,12p' environment-resolved-reviewed.yml

   In a text editor, make the reviewed copy's channels: block exactly the three lines below. Keep every exported dependency entry unchanged, and remove any top-level prefix: line so the file does not carry a machine-local path. This is a header fragment, not a complete environment file:

   channels:
     - conda-forge
     - bioconda

   Check the edited file before continuing. An export can reorder channels; do not assume it preserved the authored request or that CLI flags make its own channel block irrelevant. Do not reuse qc-tools for the copy:

   micromamba create -n qc-tools-copy -f environment-resolved-reviewed.yml --override-channels -c conda-forge -c bioconda --channel-priority strict
   micromamba run -n qc-tools-copy python --version
   micromamba run -n qc-tools-copy fastqc --version
   micromamba run -n qc-tools-copy multiqc --version
   micromamba env list

   The final list should show both names, and all three version checks must succeed. If qc-tools-copy already exists, choose another unused name consistently. The copied environment is a fresh solve on this platform, not a byte-identical lock. If it fails, retain the error and investigate pins and channel order rather than automatically switching to flexible priority.
5. Compare your observation with the prediction: Python should report a 3.11 release, and FastQC and MultiQC should each print a version and exit successfully. The environment list should contain both names. This is evidence only that these tools were installed and callable for this platform; no FASTQ was supplied and no biological quality assessment was performed. If any step fails, stop at that step, retain its full error and the output of micromamba info, and report the OS/architecture, executable version, channels, and exact command. Do not label the YAML tested just because it was saved.
6. Small variation: make a copy of the authored file, change only python=3.11 to python=3.12, and solve into a distinct new name using the same strict channel flags. Predict what version the Python check should show. If solving succeeds, verify that plus both tool versions; if not, the solve may reflect platform/package compatibility or current metadata, not a syntax error by itself. Restore the known-good file rather than loosening channels indiscriminately.
7. Optionally retain an intent-oriented export of explicitly requested packages:

   micromamba env export -n qc-tools --from-history > environment-history.yml

Keep the authored specification and, when useful, a resolved export. A history export records explicitly requested packages, but still requires a fresh solve and does not guarantee identical results. A full resolved YAML can include build and platform-specific details; a successful recreation is still not necessarily byte-identical. Test recreation rather than assuming portability, and verify the CLI options available in your installed Micromamba version. Neither file captures input data, references, analysis parameters, workflow code, or all external software: reproducibility requires those records too.

Use the environment in a workflow

Activation is a shell feature, so batch systems and scripts should initialize the shell before calling micromamba activate. A safer alternative for one command is micromamba run, which does not depend on the caller's interactive prompt.

# Run one command without activating an interactive shell
micromamba run -n qc-tools fastqc --help

# A minimal Bash job-script pattern
micromamba shell hook -s bash > /tmp/micromamba-hook.sh
source /tmp/micromamba-hook.sh
micromamba activate qc-tools
multiqc --version

For real HPC jobs, adapt the initialization to the cluster's module system and scheduler. Never hard-code a personal home directory into a shared workflow. Print the environment and tool versions into the job log so a later reader can distinguish software changes from biological or parameter changes.

Troubleshoot systematically

Command not found or activation fails

command -v micromamba
micromamba info
micromamba shell -h

# Reinitialize the shell if the command exists but activation is unavailable
micromamba shell init -s bash -r "$HOME/micromamba"
exec bash

Check that the shell matches the initialization command, that the root prefix is the one you intended, and that a new shell has loaded the updated profile. On clusters, the login shell and batch shell may read different startup files.

Solving is slow or fails

# Inspect channels and current configuration
micromamba config list
micromamba info

# Test the request without changing the environment
micromamba create -n qc-dry-run --override-channels -c conda-forge -c bioconda --channel-priority strict \
  python=3.11 fastqc --dry-run

# Search the selected channels
micromamba search -c conda-forge -c bioconda fastqc

Reduce the problem to a small request, make channels explicit, and remove unnecessary pins one at a time. Check whether every requested package supports your platform. A clean environment is usually easier to repair than a heavily modified base environment.

Mixing pip and Conda-compatible packages

Install compiled libraries and system-sensitive dependencies with Micromamba first. Use pip afterward only for genuinely missing packages. If pip replaces a shared dependency, the environment may still activate while producing runtime errors, so record and test the final state.

Disk quota, cache, and permissions

# Inspect locations before deleting anything
micromamba info

# Remove unused package archives from the Micromamba cache
micromamba clean --all

# Check available disk space and quota using your system tools
df -h "$HOME"
quota -s 2>/dev/null || true

Do not use sudo to install packages into a user-owned environment. On a cluster, request a project storage location if the home directory has a small quota, then initialize Micromamba with a root prefix there.

Optional alternative: two fresh solves from the authored request

This workflow uses the authored environment.yml saved above for two fresh solves, checks the tools in each environment, and retains a resolved export as an audit record. Unlike the reviewed-snapshot exercise, its second solve uses the original package requests and may select different compatible versions. Start with one analysis step rather than installing every program used by a laboratory.

set -euo pipefail

test -s environment.yml
micromamba create -n reproducible-qc -f environment.yml \
  --override-channels -c conda-forge -c bioconda --channel-priority strict \
  -y

micromamba run -n reproducible-qc python --version
micromamba run -n reproducible-qc fastqc --version
micromamba run -n reproducible-qc multiqc --version
micromamba env export -n reproducible-qc > reproducible-qc-resolved.yml
# Fresh solve from the authored request, not the unreviewed export.
micromamba create -n reproducible-qc-copy -f environment.yml \
  --override-channels -c conda-forge -c bioconda --channel-priority strict -y
micromamba run -n reproducible-qc-copy python --version
micromamba run -n reproducible-qc-copy fastqc --version
micromamba run -n reproducible-qc-copy multiqc --version

# Keep the command output, YAML file, and input/reference metadata with the project.
echo "Environment verification completed: $(date -Iseconds)"

Practical checklist

• Choose one primary manager and know its root prefix.
• Use separate environments for separate workflows.
• Prefer explicit conda-forge and Bioconda channels with strict priority.
• Install the initial package set together and test the actual executables.
• Keep an authored environment file and document platform-specific resolution.
• Use micromamba run or initialize the shell explicitly in jobs.
• Record versions, channels, references, parameters, and outputs for reproducibility.

Next steps

Apply this environment pattern to the single-cell RNA-seq tutorial, the WES variant-calling pipeline, or the reproducible workflow tutorial. Each analysis still needs biological quality control and documented reference data; package installation is only one part of reproducible research.