udocker is a basic user tool to execute simple docker containers in user space without requiring root privileges. Enables download and execution of docker containers by non-privileged users in Linux systems where docker is not available. It can be used to pull and execute docker containers in Linux batch systems and interactive clusters that are managed by other entities such as grid infrastructures or externally managed batch or interactive systems.

udocker does not require any type of privileges nor the deployment of services by system administrators. It can be downloaded and executed entirely by the end user. The limited root functionality provided by some of the udocker execution modes is either simulated or provided via user namespaces.

udocker is a wrapper around several tools and libraries to mimic a subset of the docker capabilities including pulling images and running containers with minimal functionality.

Important notice: We have changed the udocker tools location as of udocker 1.3.17. This affects the configuration option conf['tarball'] and environment variable UDOCKER_TARBALL, so if you are using udocker <= 1.3.16, make sure to: export UDOCKER_TARBALL=https://download.a.incd.pt/udocker/udocker-englib-1.2.11.tar.gz.

Documentation

The full documentation is available at:

How does it work

udocker is written in Python, it has a minimal set of dependencies so that can be executed in a wide range of Linux systems.

udocker does not make use of docker nor requires its presence.

udocker "executes" the containers by simply providing a chroot like environment over the extracted container. The current implementation supports different methods to mimic chroot thus enabling execution of containers under a chroot like environment without requiring privileges. udocker transparently supports several methods to execute the containers based on external tools and libraries such as:

PRoot
Fakechroot
runc
crun
Singularity

With the exception of Singularity the tools and libraries to support execution are downloaded and deployed by udocker during the installation process. This installation is performed in the user home directory and does not require privileges. The udocker related files such as libraries, executables, documentation, licenses, container images and extracted directory trees are placed by default under $HOME/.udocker.

Advantages

Can be deployed by the end-user
Does not require privileges for installation
Does not require privileges for execution
Does not require compilation, just transfer the Python code
Encapsulates several tools and execution methods
Includes the required tools already statically compiled to work across systems
Provides a docker like command line interface
Supports a subset of docker commands: search, pull, import, export, load, save, login, logout, create and run
Understands docker container metadata
Allows loading of docker and OCI containers
Supports NVIDIA GPGPU applications
Can execute in systems and environments where Linux namespaces support is unavailable
Runs both on new and older Linux distributions including: CentOS 6, CentOS 7, CentOS 8, Ubuntu 14, Ubuntu 16, Ubuntu 18, Ubuntu 20, Ubuntu 21, Alpine, Fedora, etc

Python 2 and Python 3

Since v1.3.0, udocker supports Python 2.7 and Python >= 3.6. The original udocker v1.1.x for Python 2 is no longer maintained but is still available here.

Syntax

        Commands:
          search <repo/expression>      :Search dockerhub for container images
          pull <repo/image:tag>         :Pull container image from dockerhub
          create <repo/image:tag>       :Create container from a pulled image
          run <container>               :Execute container
          run <repo/image:tag>          :Pull, create and execute container

          images -l                     :List container images
          ps -m -s                      :List created containers
          name <container_id> <name>    :Give name to container
          rmname <name>                 :Delete name from container
          rename <name> <new_name>      :Change container name
          clone <container_id>          :Duplicate container
          rm <container-id>             :Delete container
          rmi <repo/image:tag>          :Delete image
          tag <repo/image:tag> <repo2/image2:tag2> :Tag image

          import <tar> <repo/image:tag> :Import tar file (exported by docker)
          import - <repo/image:tag>     :Import from stdin (exported by docker)
          export -o <tar> <container>   :Export container directory tree
          export - <container>          :Export container directory tree
          load -i <imagefile>           :Load image from file (saved by docker)
          load                          :Load image from stdin (saved by docker)
          save -o <imagefile> <repo/image:tag>  :Save image with layers to file

          inspect <repo/image:tag>      :Return low level information on image
          inspect -p <container>        :Return path to container location
          verify <repo/image:tag>       :Verify a pulled or loaded image
          manifest inspect <repo/image:tag> :Print manifest metadata

          protect <repo/image:tag>      :Protect repository
          unprotect <repo/image:tag>    :Unprotect repository
          protect <container>           :Protect container
          unprotect <container>         :Unprotect container

          mkrepo <top-repo-dir>         :Create another repository in location
          setup                         :Change container execution settings
          login                         :Login into docker repository
          logout                        :Logout from docker repository

          help                          :This help
          run --help                    :Command specific help
          version                       :Shows udocker version

        Options common to all commands must appear before the command:
          -D                            :Debug
          --quiet                       :Less verbosity
          --repo=<directory>            :Use repository at directory
          --insecure                    :Allow insecure non authenticated https
          --allow-root                  :Allow execution by root NOT recommended

Examples

Some examples of usage:

Search container images in dockerhub and listing tags.

udocker search  fedora
udocker search  ubuntu
udocker search  debian

udocker search --list-tags ubuntu

Pull from dockerhub and list the pulled images.

udocker pull   fedora:39
udocker pull   busybox
udocker pull   iscampos/openqcd
udocker images

Pull from a registry other than dockerhub.

udocker search  quay.io/bio
udocker search  --list-tags  quay.io/biocontainers/scikit-bio
udocker pull    quay.io/biocontainers/scikit-bio:0.2.3--np112py35_0
udocker images

Pull a different architecture such as arm64 instead of amd64.

udocker manifest inspect centos/centos8
udocker pull --platform=linux/arm64 centos/centos8
udocker tag centos/centos8  mycentos/centos8:arm64

Create a container from a pulled image, assign a name to the created container and run it. A created container can be run multiple times until it is explicitly removed. Files modified or added to the container remain available across executions until the container is removed.

udocker create --name=myfed  fedora:29
udocker run  myfed  cat /etc/redhat-release

The three steps of pulling, creating and running can be also achieved in a single command, however this will be much slower for multiple invocations of the same container, as a new container will be created for each invocation. This approach will also consume more storage space. The following example creates a new container for each invocation.

udocker run  fedora:29  cat /etc/redhat-release

Execute mounting the host /home/u457 into the container directory /home/cuser. Notice that you can "mount" any host directory inside the container. Depending on the execution mode the "mount" is implemented differently and may have restrictions.

udocker run -v /home/u457:/home/cuser -w /home/user myfed  /bin/bash
udocker run -v /var -v /proc -v /sys -v /tmp  myfed  /bin/bash

Place a script in your host /tmp and execute it in the container. Notice that the behavior of --entrypoint changed from the previous versions for better compatibility with docker.

udocker run  -v /tmp  --entrypoint="" myfed  /bin/bash -c 'cd /tmp; ./myscript.sh'

udocker run  -v /tmp  --entrypoint=/bin/bash  myfed  -c 'cd /tmp; ./myscript.sh'

Execute mounting the host /var, /proc, /sys and /tmp in the same container directories. Notice that the content of these container directories will be obfuscated by the host files.

udocker run -v /var -v /proc -v /sys -v /tmp  myfed  /bin/bash

Install software inside the container.

udocker run  --user=root myfed  yum install -y firefox pulseaudio gnash-plugin

Udocker

Install / Use

README