Skip to content

Apptainer Recipe for Computer Vision Applications

This example provides an Apptainer recipe to build a container for computer vision applications with OpenCV and Ultralytics for use with the command line or an Open OnDemand Jupyter session. The container includes NVIDIA CUDA runtime, Miniforge package manager, and essential libraries including OpenCV, Ultralytics, PyTorch, and Jupyter Notebook.

We would like to thank Dr. Sambit Bhattacharya and his team at Fayetteville State University for their help with testing and providing feedback on this container.

The files for this example are available at: https://github.com/NCShare/examples/tree/main/Apptainer-Recipe-for-Computer-Vision-Applications.

Building the Computer Vision Container

Create a computervision.def file with the following recipe,

computervision.def
Bootstrap: docker
FROM: nvidia/cuda:12.8.1-cudnn-devel-ubuntu24.04

%labels
    Author Uthpala Herath
    Version v1.0.0

%help
  This image contains nvidia CUDA 12.8.1, ubuntu 24.04, Jupyter Notebook,
  and Python libraries needed for computer vision tasks including OpenCV and Ultralytics.

%post
  set -eux
  export TZ="America/New_York"
  ln -snf /usr/share/zoneinfo/${TZ} /etc/localtime || true
  echo "${TZ}" > /etc/timezone
  export DEBIAN_FRONTEND=noninteractive

  # apt install packages
  apt update
  apt install -y --no-install-recommends build-essential wget curl libcurl4 zlib1g zlib1g-dev locales libx11-6 vim \
    libglib2.0-0 \
    libgl1 \
    libglvnd0 \
    libegl1 \
    libsm6 \
    libxext6 \
    libxrender1 \
    libgtk-3-0 \
    libgdk-pixbuf2.0-0
  sed -i '/en_US.UTF-8/s/^# //g' /etc/locale.gen
  locale-gen en_US.UTF-8
  update-locale LANG=en_US.UTF-8
  apt-get clean
  rm -rf /var/lib/apt/lists/*

  # --- Install Miniforge ---
  CONDA_DIR="/opt/conda"
  install_dir="$(dirname "${CONDA_DIR}")"

  mkdir -p "${install_dir}"
  wget -q "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh" -O /tmp/miniforge.sh
  /bin/bash /tmp/miniforge.sh -b -p "${CONDA_DIR}"
  rm -f /tmp/miniforge.sh

  # ensure non-root users can read/execute files
  chmod -R a+rX "${CONDA_DIR}" || true
  sync

  # --- Install packages ---
  "${CONDA_DIR}/bin/conda" install -y jupyter jupyterlab
  "${CONDA_DIR}/bin/conda" install -y anaconda::glib
  "${CONDA_DIR}/bin/pip3" install --no-cache-dir scipy numpy matplotlib pandas seaborn networkx requests safetensors ultralytics torch torchvision ultralytics ultralytics-thop opencv-python

  # Clean package caches
  "${CONDA_DIR}/bin/conda" clean -afy || true

%environment
 export LANG="en_US.UTF-8"
 export LC_ALL="en_US.UTF-8"
 export TZ="America/New_York"

  # conda env
  export CONDA_DIR="/opt/conda"
  export PATH="${CONDA_DIR}/bin:${PATH}"
  export CONDA_ENVS_PATH="${CONDA_DIR}/envs"
  export CONDA_AUTO_ACTIVATE_BASE="true"

# Ensure conda shell functions are registered for runtime shells
  if [ -f "${CONDA_DIR}/etc/profile.d/conda.sh" ]; then
    . "${CONDA_DIR}/etc/profile.d/conda.sh"
  fi

%runscript
if [ $# -eq 0 ]; then
  exec /bin/bash -l -i
else
  exec "$@"
fi

Then build the container with:

export APPTAINER_CACHEDIR=/work/${USER}/tmp
export APPTAINER_TMPDIR=/work/${USER}/tmp
apptainer build computervision.sif computervision.def

For global access, move the built container to /opt/apps/containers/user/computervision.sif. For automated building and deployment to NCShare, refer to the Cluster Software guide.

It is important to note that when importing OpenCV, you may encounter system library dependency errors such as,

ImportError: libgthread-2.0.so.0: cannot open shared object file: No such file or directory

This occurs because OpenCV requires system libraries that cannot be installed through conda alone. The solution is to install the required system libraries via apt during container building,

# System libraries installed in the %post section:
libglib2.0-0 \
libgl1 \
libglvnd0 \
libegl1 \
libsm6 \
libxext6 \
libxrender1 \
libgtk-3-0 \
libgdk-pixbuf2.0-0

These libraries provide the graphics support that OpenCV needs for image processing and display operations. The recipe above includes these installations.

Using the Computer Vision Container

To use the container with Open OnDemand, follow these steps:

  1. Navigate to Open OnDemand
  2. Launch the Jupyter Lab application
  3. Under "Apptainer Container File", select your built container (computervision.sif)
  4. Configure other settings as needed (GPU, memory, etc.)
  5. Launch the session

You may also interact with the container directly from the command line to verify the computer vision libraries are working correctly.

Access the container shell,

apptainer shell --nv computervision.sif

Once inside the container, verify OpenCV and Ultralytics installation,

Apptainer> ipython
Python 3.12.12 | packaged by conda-forge | (main, Oct 22 2025, 23:25:55) [GCC 14.3.0]
Type 'copyright', 'credits' or 'license' for more information
IPython 9.8.0 -- An enhanced Interactive Python. Type '?' for help.
Tip: IPython supports combining unicode identifiers, eg F\vec<tab> will become F⃗, useful for physics equations. Play with \dot \ddot and others.

In [1]: import cv2

In [2]: cv2.__version__
Out[2]: '4.12.0'

In [3]: import ultralytics

In [4]: ultralytics.__version__
Out[4]: '8.3.244'