1) Using udocker to run containers

(Document compiled by aco@tauex.tau.ac.il)

The udocker platform lets anyone run containers from the Docker repository or from other repositories. udocker does not make use of Docker nor requires its installation

Containers are pulled to a local repository (directory hierarchy) which is owned by the user. Since containers may be too large to fit in your allowed storage quota you are advised to use a temporary scratch area.

2) How to create a local repository in /vol/scratch

(Note: if you have a storage space of your own, you can substitute /vol/scratch with the path where your storage resides).

mkdir -p /vol/scratch/<your-username>/

udocker mkrepo /vol/scratch/<your-user-name>/<name of my repo>

Make sure to define an environment variable (add line in .bashrc or in .tcshrc):

To find out which shell you are using, run the command "echo $SHELL"

3) Setting UDOCKER_DIR environment variable

For bash users (run only once):

echo "export UDOCKER_DIR=/vol/scratch/<your-user-name>/<name of my repo>" >> ~/.bashrc && source ~/.bashrc

For tcsh users (run only once):

echo "setenv UDOCKER_DIR /vol/scratch/<your-user-name>/<name of my repo>" >> ~/.tcshrc && source ~/.tcshrc

If you don't create a repository and define the UDOCKER_DIR environment variable, udocker will create a repository under your home directory, in the directory ".udocker". This can be a problem if you do not have enough storage/quota. In most cases, it is recommended to use /vol/scratch.

Warning: Files and directories in /vol/scratch are automatically removed every week. This is not a problem as long as you don't save dynamic content (such as the code that you develop, output of your jobs, etc.) in /vol/scratch. You can always pull and create your containers again after they disappear. Make sure to use your home directory for dynamic content (see step 6 below related to --bindhome).

4) Pulling images and running containers

You can search container images in the Docker repository using

udocker search [-a] <STRING>                          #The -a option displays all matching entries without pausing.

Here we pull an image of the latest Ubuntu container from the Docker repository:

udocker pull ubuntu:latest

udocker create --name=<name of your container> ubuntu:latest

udocker run <name of your container>

(and now from within the container):

cat /etc/lsb-release


# or, run it as a script from the command line

udocker run <name of your container> /bin/bash <<EOF

cd /etc

cat lsb-release


# or a one-liner (from host machine, not from inside container):

udocker run <name of your container> /bin/bash -c 'cat /etc/lsb-release'

This sequence allows the created container to be executed many times. Containers can also be pulled, created and executed in a single step. However, in this case a new container is created for every run invocation thus occupying more storage space.

Note: The command udocker is to be run only from host machine and not from inside container.

Which user am I inside container?

Within the container you are root, you can install packages and perform other tasks that only root can do. However, your root permissions are mapped to you real user and group IDs in the host machine.

6) Directory mapping

You can make you home directory appear inside the container by using the --bindhome flag:

udocker run --bindhome <name of your container>

You can map any host file or directory to appear inside the container by using the --volume flag:

udocker run --bindhome --volume=/usr/local:/mnt/local <name of your container>

This will map /usr/local from the host machine to /mnt/local within the container. You can issue multiple instances of --volume in your command if you wish.

7) Installing packages of software as needed

If you need additional packages to be used in the container, you can install them. For instance:

udocker run <name of your container>

(and then from within the container):

apt update

apt install nano

Now you can run nano. You don't have to install it again in the future because the installation is persistent (as long as the container hasn't been deleted): udocker preserves all installation and modifications in its root file system. You can find it in $UDOCKER_DIR/containers/<name of your container>/ROOT

 A more detailed installations guide:

  1. From outside the container, change execmode:

    udocker setup --execmode=P2 <name of your container>

  2. Run the container:

    udocker run --containerauth --user=root <name of your container>

  3. Recommended - pre-installation:

    apt update; apt upgrdae -y; export DEBIAN_FRONTEND=noninteractive 

  4. Install:

    apt install python3.9 python3.9-dev python3-pip

    apt install nano

    apt install build-essential

  5. Exit the container:


  6. Return the execution mode:

    udocker setup --execmode=P1

  7. Run the container for use:

    udocker run --bindhome <name of your container>

  8. link:


8) Using X11 for graphical interface

You can run X11 applications and get the output on your host if you use X11 to login to the Linux host machine, or from Windows, if you use, for instance, MobaXterm.


First, find out the ip address of your host machine, then run following command inside the container:

For bash:

export DISPLAY=<host_ip>:0

For tcsh:

setenv DISPLAY <host_ip>:0

Then run whichever 11X application you'd like, xeyes, for example:


If xeyes is not available within the Ubuntu container, you can install it:

apt update && apt install x11-apps


Additional information and documentation: