Skip to main content

1.7 Mamba and Conda Environments

SECTION 1: One-off installation

What are Conda/Mamba Environments?

Whilst the CCB has a module system to load pre-installed bioinformatics software, sometimes you may want to install your own software or specific versions of tools. This is where Conda and Mamba environments come in handy.

I would suggest using Mamba/Conda only as a last resort if the software you need is not available via the module system on the CCB.

Conda and Mamba are package managers that help you install and manage software dependencies for bioinformatics. They create isolated environments where you can install specific versions of tools without conflicts.

Mamba is a faster, drop-in replacement for Conda that uses the same commands and syntax.

Why Use Environments?

  • Isolation: Keep different projects with different requirements separate
  • Reproducibility: Ensure you’re using the same software versions across analyses
  • No conflicts: Different tools can require different versions of dependencies
  • Easy installation: Install bioinformatics tools without root access
  • Version control: Easily switch between tool versions

Installing Mamba on the CCB

1) Move to your directory in the project space and make a folder

cd /project/higgslab/your_username/
mkdir mamba_installation
cd mamba_installation

2) Installing Miniforge - Conda and Mamba in one easy step

# Download installer
## You do not need to change uname in the command below, it will automatically detect your OS
wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh

3) Run the installer

bash Miniforge3-$(uname)-$(uname -m).sh -b -p conda

-b tells the installation script to run without prompts and not to modify your .bashrc or .bash_profile file (b stands for “batch mode”).

-p sets the path where you want conda to be installed. This can be an absolute or relative path. In this example, the command will create a conda directory in the working directory, and install everything within it.

4) Activate Conda and Mamba (for this session)

# Activate conda installation - by sourcing the conda.sh script 
# we will need the full path to be correct and add your username at $USER - use tab autocompletion to help avoid errors
source /project/higgslab/$USER/mamba_installation/conda/etc/profile.d/conda.sh

# Activate mamba installation - by sourcing the mamba.sh script 
source /project/higgslab/$USER/mamba_installation/conda/etc/profile.d/mamba.sh

# Activate base environment to move into the default conda/mamba software environment
mamba activate base

5) Test your source command has worked by trying:

which conda
which mamba 
conda --help 
mamba --help

6) Add aliases to activate Conda more easily in new Bash sessions

Let’s add the source and mamba activate commands from the previous section to our ~/.bash_aliases files, so that we can activate Conda easily when we log onto the server

Copy your source commands from step 4 above paste into the .bash_aliases file in your home directory.

# open your ~/.bash_aliases in nano 
nano ~/.bash_aliases 

# Create an alias to load conda/mamba and change your path to include your project directory and username
alias load_mamba='source /project/higgslab/$USER/mamba_installation/conda/etc/profile.d/conda.sh && source /project/higgslab/$USER/mamba_installation/conda/etc/profile.d/mamba.sh '

Close and save your .bash_aliases file (CTRL + X, Y, ENTER)

Update your ~/.bashrc file so that the aliases are set up when you log in by adding the following line to the end of the file:

source ~/.bash_aliases

After refreshing your terminal (or logging out and back in), you can now load conda/mamba with the command:

load_mamba

7) Add channels for bioconda (one-time setup)

We can use Mamba to search for software packages to install. However in order to find packages, Mamba needs to know which online websites it can search for them – those are called ‘channels’.

Now, let us add appropriate channels from where we know we can get all the software we need (and trust).

conda config --add channels defaults
conda config --add channels conda-forge
conda config --add channels bioconda

We have added 3 channels here:

  • defaults: this channel contains widely used software that has been packaged by the Conda and Anaconda teams themselves.
  • conda-forge: this channel contains a wide variety of packages that have been packaged by diverse people in the programming/computational community.
  • bioconda: this contains biology-oriented programs that have been packaged by diverse people in the computational biology community.

You can also repeat these steps on your local machine if you wish to use Mamba/Conda there.

SECTION 2: Using Mamba Environments

Basic Mamba Commands

Remember to begin using Mamba, you need to load it first in your terminal session when connected to the CCB clusters:

load_mamba
mamba activate base

Activating and Deactivating

# Activate an environment
mamba activate myenv

# Deactivate current environment
mamba deactivate

Creating Environments

Environments allow you to create spaces with combinations of packages to use. You can create a new environment with specific packages and versions, or as specified in an environment YAML file.

The environment YAML file is a convenient way to define the environment in a gihub repository and share it with others and across different systems. It is a text file that lists the packages and their versions needed for a project.

# To create a new basic environment called 'myenv'
mamba create -n myenv

# Environment with specific Python version
mamba create -n myenv python=3.9

# Environment with specific tools
mamba create -n rnaseq fastqc star salmon

# Create environment from a environment YAML file
mamba env create -f environment.yml

Installing Packages

# Install a package in active environment
mamba install samtools
# type 'Y' at the prompt to confirm the installation

# Install specific version
mamba install samtools=1.15

# Install multiple packages
mamba install fastqc trimmomatic bowtie2

Listing and Managing Environments

# List all environments
mamba env list

# List packages in current environment
mamba list

To Remove an Environment

# First deactivate the environment
mamba deactivate

# remove the environment
mamba remove --name genomics_tools_env --all

# Check your list of environments
mamba env list

Example: Creating an ATAC-seq Environment

# Create environment with all tools needed for ATAC-seq
mamba create -n atacseq \
    fastqc \
    trimmomatic \
    bowtie2 \
    samtools \
    macs2 \
    deeptools \
    bedtools

# Activate it
mamba activate atacseq

# Now all tools are available
fastqc --version
bowtie2 --help

Clear the cache

# Clear package cache to free up space
mamba clean --all

Environment Files

Exporting an Environment

Save your environment for reproducibility:

# Export to YAML file
mamba env export > environment.yml

# Export only explicitly installed packages
mamba env export --from-history > environment.yml

Creating from Environment File

Often for homemade pipelines, you will need to recreate an environment from a template file, often from YAML files ending .yml that contains all the packages and versions needed to run the pipeline.

# Create environment from YAML
mamba env create -f environment.yml

# Update existing environment
mamba env update -f environment.yml

Example environment.yml

name: atacseq
channels:
  - conda-forge
  - bioconda
  - defaults
dependencies:
  - python=3.9
  - fastqc=0.11.9
  - trimmomatic=0.39
  - bowtie2=2.4.5
  - samtools=1.15
  - macs2=2.2.7
  - deeptools=3.5.1
  - bedtools=2.30.0

Useful Commands Summary

Category Command Description
Environment Management
mamba create -n myenv Create environment
mamba activate myenv Activate environment
mamba deactivate Deactivate environment
mamba env list List all environments
mamba env remove -n myenv Remove environment
Package Management
mamba install package Install package
mamba install package=1.15 Install specific version
mamba update package Update package
mamba remove package Remove package
mamba list List installed packages
mamba search package Search for package
Environment Files
mamba env export > env.yml Export environment
mamba env create -f env.yml Create from file
mamba env update -f env.yml Update from file
Information
mamba info Show mamba info
mamba info --envs List environments
mamba --version Show version

SECTION 3: Sourcing Mamba Environments in Pipelines

If there is an exisiting environment built in the project/higgslab/ directory, made by someone else, you can source that environment in your homemade pipelines to ensure you have the correct software versions to run the pipeline.

# Activate the environment at the start of your pipeline script
source /project/higgslab/their_username/mamba_installation/conda/bin/activate name_of_environment

Resources