Running Ubuntu MATE inside Docker container by x11docker with GUI


An alternative for virtual machine is a Docker container.
Containers are usually running without GUI.
To get GUI one can utilize the famous and well-designed x11docker project.
It already has pre-configured container with MATE desktop, which is based on Debian Buster. And what is interesting - such image has 10K+ downloads and is most popular variant.

Below is the method of using x11docker to run Ubuntu MATE.

Quick start

To run Ubuntu MATE with x11docker one should follow the following steps:

  1. Install Docker

    # to remove previously installed Docker, uncomment next line
    # sudo apt-get remove docker docker-engine containerd runc
    sudo apt-get update
    sudo apt-get install apt-transport-https ca-certificates curl gnupg lsb-release
    curl -fsSL | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
    echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] \
    $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
    sudo apt-get update
    sudo apt-get install docker-ce docker-ce-cli
  2. Install dependencies

    sudo apt-get install git xserver-xephyr
  3. Add current user to the docker group

    sudo usermod -a -G docker $USER

    then reboot machine.

  4. Prepare folder for Docker repository

    mkdir ~/Docker
    cd ~/Docker
    git clone
    cd dockerfile-x11docker-ubuntu-mate
    chmod +x x11docker
    sudo mv x11docker /usr/local/bin/x11docker
  5. Build default Ubuntu MATE 20.04 LTS image locally

    docker build ~/Docker/dockerfile-x11docker-ubuntu-mate -t ubuntu-mate:focal
  6. Run Docker container with Ubuntu MATE

    • minimal, using default settings

      x11docker --desktop ubuntu-mate:focal
    • more functional, using extra options

      x11docker --desktop ubuntu-mate:focal --sudouser --dbus --home --share ~/Public --clipboard --pulseaudio  --xtest --init=systemd

      where options are the following:

      • --sudouser – allows running commands with sudo and password is x11docker;

      • --dbus – DBUS session bus for desktop and other applications;

      • --home – creates a host directory in ~/.local/share/x11docker/IMAGENAME that is shared with the container and mounted as its HOME directory;

      • --share ~/Public – share folder between host system and container;

      • --clipboard – share clipboard;

      • --pulseaudio – share audio;

      • --xtest – use XTest X11 extension (needed for Onboard);

      • --init=systemd – use systemd as init system inside container.

        Other options are available in x11docker --help output.
        The result will look like shown below:

    One can run almost any preinstalled application in the opened graphical MATE session or install any other by using APT.

Advanced usage

Advanced usage allows one to build and run any supported Ubuntu MATE version inside Docker container with X11.

To build the container use:

  • Ubuntu 18.04 LTS (bionic)

    export VER=bionic; docker build --build-arg "VER=$VER" ~/Docker/dockerfile-x11docker-ubuntu-mate -t ubuntu-mate:$VER
  • Ubuntu 20.04 LTS (focal, default)

    export VER=focal; docker build --build-arg "VER=$VER" ~/Docker/dockerfile-x11docker-ubuntu-mate -t ubuntu-mate:$VER
  • Ubuntu 20.10 (groovy)

    export VER=groovy; docker build --build-arg "VER=$VER" ~/Docker/dockerfile-x11docker-ubuntu-mate -t ubuntu-mate:$VER
  • Ubuntu 21.04 (hirsute)

    export VER=hirsute; docker build --build-arg "VER=$VER" ~/Docker/dockerfile-x11docker-ubuntu-mate -t ubuntu-mate:$VER
  • upcoming Ubuntu 21.10 (impish)

    export VER=impish; docker build --build-arg "VER=$VER" ~/Docker/dockerfile-x11docker-ubuntu-mate -t ubuntu-mate:$VER

To run the container from the same terminal use:

x11docker --desktop ubuntu-mate:$VER --sudouser --dbus --home --share ~/Public --clipboard --pulseaudio  --xtest --init=systemd

or explicitly specify needed version by replacing $VER variable with actual version as shown below:

x11docker --desktop ubuntu-mate:groovy --sudouser --dbus --home --share ~/Public --clipboard --pulseaudio  --xtest --init=systemd

Notes about legacy versions

For some purposes one may need to run Ubuntu MATE versions like 12.04 LTS, 14.04 LTS and 16.04 LTS inside Docker container without systemd.

Building and run commands are below:

  • Ubuntu 12.04 LTS (precise)

    export VER=precise; docker build --build-arg "VER=$VER" ~/Docker/dockerfile-x11docker-ubuntu-mate -t ubuntu-mate:$VER
    x11docker --desktop ubuntu-mate:precise --sudouser --dbus --home --share ~/Public --clipboard --pulseaudio --xtest --runasroot 'chmod 0440 /etc/sudoers'
  • Ubuntu 14.04 LTS (trusty)

    export VER=trusty; docker build --build-arg "VER=$VER" ~/Docker/dockerfile-x11docker-ubuntu-mate -t ubuntu-mate:$VER
    x11docker --desktop ubuntu-mate:trusty --sudouser --dbus --home --share ~/Public --clipboard --pulseaudio --xtest
  • Ubuntu 16.04 LTS (xenial)

    export VER=xenial; docker build --build-arg "VER=$VER" ~/Docker/dockerfile-x11docker-ubuntu-mate -t ubuntu-mate:$VER
    x11docker --desktop ubuntu-mate:xenial --sudouser --dbus --home --share ~/Public --clipboard --pulseaudio --xtest

Above will give one opportunity to learn the history of Ubuntu MATE.


This gives almost unlimited possibilities for experiments.
But remember, that container is reseted on every launch, only data in shared folder stays saved.

Notes and limitations:

  1. MATE Screensaver is removed from all images.
  2. Both Snap and FlatPak currently do not work in the containers.
  3. Ubuntu MATE 12.04 LTS, 14.04 LTS and 16.04 LTS do not use systemd in the container.
  4. Ubuntu MATE 18.04 LTS and 20.04 LTS do not have any workaround applied in the Dockerfile.
  5. Ubuntu MATE 20.10 have the following workarounds: to avoid systemd lock-up acpid, acpi-support and sssd-common packages are removed;
  6. Ubuntu MATE 21.04 have the following workarounds: to avoid systemd lock-up acpid and acpi-support packages are removed, the redshift-gtk package is removed as not functional;
  7. Upcoming Ubuntu MATE 21.10 have the following workarounds: to avoid systemd lock-up acpid and acpi-support packages are removed, the redshift-gtk package is removed as not functional, the container should be run with x11docker --desktop --home --share ~/Public --sudouser --dbus --clipboard --pulseaudio --xtest --init=systemd -- --security-opt seccomp=unconfined -- ubuntu-mate:impish;
  8. Adding and removing PPAs, installing software from them is normally possible;
  9. WINE applications run well;
  10. Graphical applications with root (pkexec-, sudo/gksu/gksudo/kdesu/kdesudo-based) rights will not run because of isolation;
  11. There is something wrong with package from official Ubuntu repositories - it does not allow one to build image of Ubuntu 21.04, see bug 1918021 for details;
  12. New versions of x11docker require --home to be declared when --share includes location from host home folder.

Please help,
Unable to find image 'x11docker:latest' locally
docker: Error response from daemon: pull access denied for x11docker, repository does not exist or may require 'docker login': denied: requested access to the resource is denied.
See 'docker run --help'.
Thank you in advance

Welcome to the Ubuntu MATE community, v5Q!

It seems that you are following above guide partially. Please run steps 1 - 5 (especially 5!) again.

1 Like