Honfi001 at 15:10, 17 August 2026

2026-08-17T15:10:11Z

← Older revision		Revision as of 15:10, 17 August 2026
Line 1:		Line 1:
	{{DISPLAYTITLE:~~Totorial~~: Conda in an Apptainer Container}}		{{DISPLAYTITLE:Tutorial: Conda in an Apptainer Container}}
	= Running a Conda Environment in a Container =		= Running a Conda Environment in a Container =

Honfi001: Created page with "{{DISPLAYTITLE:Totorial: Conda in an Apptainer Container}} = Running a Conda Environment in a Container = Sometimes a piece of software is published only as a conda package, with no module, no Python-only equivalent and no ready-made image. Building it into a container is the cleanest way to run it on Anunna: the environment is created once, on a compute node, and afterwards it is a single file that behaves the same way every time you use it. Read Python/Conda firs..."

2026-08-17T15:09:47Z

Created page with "{{DISPLAYTITLE:Totorial: Conda in an Apptainer Container}} = Running a Conda Environment in a Container = Sometimes a piece of software is published only as a conda package, with no module, no Python-only equivalent and no ready-made image. Building it into a container is the cleanest way to run it on Anunna: the environment is created once, on a compute node, and afterwards it is a single file that behaves the same way every time you use it. Read Python/Conda firs..."

New page

{{DISPLAYTITLE:Totorial: Conda in an Apptainer Container}}
= Running a Conda Environment in a Container =

Sometimes a piece of software is published only as a conda package, with no module, no Python-only equivalent and no ready-made image. Building it into a container is the cleanest way to run it on Anunna: the environment is created once, on a compute node, and afterwards it is a single file that behaves the same way every time you use it.

Read [[Python/Conda]] first if you have not already. This tutorial is the last resort described at the end of that page, not the recommended route.

'''Important:''' Before you begin, make sure the following are in place:

* You are running on a '''compute node''', not a login node. Request an interactive session first — see [[Interactive Jobs]].
* Your <code>.sif</code> image files should be stored on '''Lustre''', not in your home directory. SIF files can be large and will eat through your home quota fast.
* Set your Apptainer cache to Lustre as well. Add this to your session (or your <code>.bashrc</code>):

<syntaxhighlight lang="bash">
export APPTAINER_CACHEDIR=$myScratch/apptainer_cache
</syntaxhighlight>

== Getting Started ==

Load the required modules:

<syntaxhighlight lang="bash">
module reset
module load utilities Apptainer
</syntaxhighlight>

== Three things to know first ==

* '''A container should not be your first move.''' Always prefer software we already provide as [[Environment Modules|modules]], or a [[Python/Modules#Virtual environments|virtual environment]] built on one of our Python modules. Those are compiled for this machine and we are far better placed to help you when something goes wrong. [[Support|Ask us]] if what you need is missing.

* '''This tutorial uses micromamba, not conda.''' Micromamba is a single small program that installs conda packages, and it takes them from conda-forge and bioconda rather than from Anaconda's own repository. That keeps you clear of the licensing conditions described in [[Python/Conda#How they differ]].

* '''The image we build is read-only.''' Everything the environment needs is decided up front and baked in. Do not try to install software interactively inside a running container: the changes will not survive, and you lose the one real advantage of doing this, which is that the result is reproducible.

== Step 1: Describe the environment ==

Create a file called <code>environment.yml</code>. This is where you name the environment, list the packages you want, and say which repositories to take them from.

<syntaxhighlight lang="yaml">
name: base
channels:
- conda-forge
- bioconda
dependencies:
- python
- pip
- star
- bwa
- multiqc
</syntaxhighlight>

Two notes on this file. Keep the name as <code>base</code>, because that is the environment micromamba's image already has and installing into it saves a step. And for real work, pin your versions — <code>multiqc=1.29</code> rather than <code>multiqc</code> — otherwise rebuilding the image in six months will quietly give you different software.

== Step 2: Write the definition file ==

A '''definition file''' describes how the container is built, step by step. Create <code>image.def</code>:

<syntaxhighlight lang="bash">
Bootstrap: docker
From: mambaorg/micromamba:latest

%files
environment.yml /environment.yml

%post
micromamba install -n base --file /environment.yml && \
micromamba clean --all --yes
</syntaxhighlight>

Each part in turn:

=== <code>Bootstrap</code> and <code>From</code> ===

Start from a Docker image that already has micromamba installed, so we do not have to install it ourselves.

=== <code>%files</code> ===

Copy <code>environment.yml</code> from your directory on Anunna into the container, so the next step can read it.

=== <code>%post</code> ===

Run micromamba inside the container to install everything listed in the file, then delete its download cache. That last part matters: without <code>clean</code>, the cache is baked into the image and can easily double its size.

== Step 3: Build the image ==

<syntaxhighlight lang="bash">
apptainer build image.sif image.def
</syntaxhighlight>

This takes a few minutes and produces a single file, <code>image.sif</code>, containing the whole environment.

If the build fails complaining about directories from the host, clear Apptainer's bind list for the duration of the build:

<syntaxhighlight lang="bash">
APPTAINER_BIND=' ' apptainer build image.sif image.def
</syntaxhighlight>

== Testing the image ==

Check that the software is really there:

<syntaxhighlight lang="bash">
apptainer run image.sif multiqc --help
</syntaxhighlight>

You should see MultiQC's own help text, beginning with its version number and a usage line. If instead you get an error saying the command was not found, read the note below.

'''Use <code>run</code>, not <code>exec</code>.''' The micromamba image activates the environment as it starts up, and <code>apptainer run</code> goes through that startup step while <code>apptainer exec</code> skips it. With <code>exec</code> you will most likely be told the command cannot be found, even though it is installed.

== Using it in a job ==

<syntaxhighlight lang="bash">
#!/bin/bash
#SBATCH --job-name=multiqc
#SBATCH --time=1:00:00
#SBATCH --cpus-per-task=4
#SBATCH --mem=16G

module load utilities Apptainer

apptainer run --bind /lustre $myNobackup/images/image.sif multiqc /path/to/results
</syntaxhighlight>

Apptainer does not automatically make every filesystem visible inside the container, so <code>--bind /lustre</code> ensures your data can be read.

== Where to keep your images ==

Image files are large. Keep them on Lustre, under <code>$myNobackup</code>, and not in your home directory.

If several people in your group use the same software, put one copy somewhere shared instead of each keeping their own — see [[Shared Storage]]. A container is a single file and is identical for everyone who runs it, which is precisely what makes sharing it worthwhile.

One habit worth forming: identify an image by what is inside it, using <code>apptainer inspect</code>, rather than by trusting its file name.

== Summary ==

{| class="wikitable"
! Step !! Command
|-
| Load Apptainer || <code>module reset && module load utilities Apptainer</code>
|-
| Describe the environment || Write <code>environment.yml</code>
|-
| Describe the container || Write <code>image.def</code>
|-
| Build the image || <code>apptainer build image.sif image.def</code>
|-
| Run something in it || <code>apptainer run image.sif <command></code>
|-
| Inspect it || <code>apptainer inspect image.sif</code>
|}

== See also ==

* [[Python/Conda]]
* [[Apptainer]]
* [[Tutorials/Apptainer-Introduction]]
* [[Tutorials/Apptainer-DefinitionFiles]]
* [[Interactive Jobs]]
* [[Batch Jobs]]
* [[Shared Storage]]

== External links ==

* [https://mamba.readthedocs.io/en/latest/user_guide/micromamba.html micromamba documentation]
* [https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#create-env-file-manually Writing an environment.yml file]
* [https://apptainer.org/docs/user/main/definition_files.html Apptainer definition files]
* [https://depot.galaxyproject.org/singularity/ Prebuilt bioconda container images]

Tutorials/Apptainer-Conda - Revision history

Honfi001 at 15:10, 17 August 2026