x11docker - Man Page

Run GUI applications and desktop environments in containers

Examples (TL;DR)


To run a container on a new X server:

x11docker [Options] IMAGE [COMMAND]

x11docker [Options] -- IMAGE [COMMAND [ARGS ...]]

x11docker [Options] -- [CUSTOM_RUN_OPTIONS] -- IMAGE [COMMAND [ARGS ...]]

To run a host application on a new X server:

x11docker [Options] --backend=host -- COMMAND [ARGS ...]


Runs GUI applications and desktop environments in containers. Supports docker, podman, and (experimental) nerdctl. Can run X servers from host or in containers of image x11docker/xserver. Can also provide X servers to host applications. x11docker always runs a fresh container from image and discards it afterwards.

Optional features

* GPU hardware acceleration
* Sound with pulseaudio or ALSA
* Clipboard sharing
* Printer access
* Webcam access
* Persistent home folder
* Wayland support
* Language locale creation
* Several init systems and DBus in container
* Support of several container runtimes and backends

Focus on security

* Avoids X security leaks using additional X servers.
* Container user is same as host user to avoid root in container.
* Restricts container capabilities to bare minimum.

x11docker sets up an unprivileged container user with password x11docker and restricts container capabilities. Some applications might behave different than with a regular docker|podman run command due to these security restrictions. Achieve a less restricted setup with --cap-default or --sudouser.


Short options do not accept arguments.


Display this message and exit.


Show license of x11docker (MIT) and exit.


Show x11docker version and exit.

Basic settings


Container backend to use, or host for no container.

-d,  --desktop

Indicate a desktop environment in image.

-i,  --interactive

Run with an interactive tty to allow shell commands.

--rootless [=yes|no]

Use (or disallow) rootless backend. Default behaviour without option --rootless:
--backend=docker: rootful unless environment variable DOCKER_HOST is set.
--backend=podman: rootless except started as root.
--backend=nerdctl: rootless except started as root

--xc [=yes|no|BACKEND]

Run X server in container of image x11docker/xserver. BACKEND can specify one of docker|podman|nerdctl.


Only start an empty X server.

Host integration

--alsa [=ALSA_CARD]

Sound with ALSA. You can define a desired sound card with ALSA_CARD. List of available sound cards: aplay -l

-c,  --clipboard [=yes|no|oneway|superv|altv] Share clipboard with host.

Possible arguments:
yes     Share clipboard in both directions. Includes middle-mouse-click selection.
oneway  Copy clipboard from container to host only. Includes middle-mouse-click selection.
superv  Keys [SUPER][v] copy clipboard from host to container. Does not copy middle-mouse-click to container. Otherwise same as oneway.
altv    Same as superv but using keys [ALT][v].
no      Do not share clipboard.

-g,  --gpu [=yes|no|iglx|virgl] GPU access for hardware accelerated OpenGL.

Works best with open source drivers on host and in image. For closed source nvidia drivers regard terminal output. Direct rendering supported by few X server options only.
iglx enables indirect rendering (--xorg only).
virgl allows GPU access for all X servers, but with limited performance and with --xc only.

-I,  --network [=NET]

Allow internet access. (i.e. allow Docker default.) For optional argument NET see Docker documentation of docker run option --network. Docker default is bridge.

-l,  --lang [=LOCALE]

Set language variable LANG=LOCALE in container. Without arg LOCALE host variable --lang=$LANG is used. If LOCALE is missing in image, x11docker generates it with localedef in container (needs locales package). Examples for LOCALE: ru, en, de, zh_CN, cz, fr, fr_BE.

-P,  --printer [=MODE] Share host printers through cups server.

Optional MODE can be socket or tcp. Default: socket

-p,  --pulseaudio [=MODE]

Sound with pulseaudio. Needs pulseaudio on host and in image. Optional arg MODE can be socket, tcp or host. tcp mode needs network access with --network.


Share host webcam device files.

Shared host folders or volumes

-m,  --home [=ARG]

Create a persistent HOME folder for data storage. Default: Uses ~/.local/share/x11docker/IMAGENAME. ARG can be another host folder or a volume. (~/.local/share/x11docker has a softlink to ~/x11docker.) (Use --homebasedir to change this base storage folder.)


Share host file or folder ARG. Read-only with ARG:ro . Device files in /dev can be shared, too. ARG can also be a volume instead of a host folder.

X server options


Automatically choose X server (default). Influenced notably by options --desktop, --gpu, --wayland, --wm.

-h,  --hostdisplay

Share host display :0. Quite bad container isolation! Least overhead of all X server options.

-a,  --xpra

Nested X server supporting seamless and --desktop mode.


Like --xpra --xc, but runs xpra client on host.

-A,  --xpra-xwayland

Like --xpra, but supports option --gpu.


Like --xpra2, but supports option --gpu.

-n,  --nxagent

Nested X server supporting seamless and --desktop mode. Faster than --xpra, but can have compositing issues.

-y,  --xephyr

Nested X server for --desktop mode. Without --desktop a host window manager will be provided (option --wm).

-Y,  --weston-xwayland

Desktop mode like --xephyr, but supports option --gpu. Runs from console, within X and within Wayland.

-x,  --xorg

Core Xorg server. Runs ootb from console. Switch tty with <CTRL><ALT><F1>....<F12>. Always switch to a black tty before switching to X to avoid possible crashes.

Special X server options

-t,  --tty

Terminal only mode. Does not run an X or Wayland server.


Invisible X server using Xvfb. Can be used for custom access with xpra or VNC.

-X,  --xwayland

Blanc Xwayland, needs a running Wayland compositor.


X server to run in Cygwin/X on MS Windows.


X server wrapper for VcXsrv and Xwin on MS Windows.

Wayland instead of X

-W,  --wayland

Automatically set up a Wayland environment. Chooses one of following options and regards --desktop.

-T,  --weston

Weston without X for pure Wayland applications. Runs in X, in Wayland or from console.

-K,  --kwin

KWin without X for pure Wayland applications. Runs in X, in Wayland or from console.

-H,  --hostwayland

Share host Wayland without X for pure Wayland apps.

X and Wayland appearance options

--border [=COLOR] Draw a colored border in windows of xpra.

Argument COLOR can be e.g. orange or #F00. Thickness can be specified, too, e.g. red,3. Default: blue,1


dpi value (N dots per inch) to submit to X clients. Influences font size of some applications.

-f,  --fullscreen

Run in fullscreen mode.


Multiple virtual monitors for Weston or KWin.


Rotate display (--xorg, --weston and --weston-xwayland) Allowed values: 0, 90, 180, 270, flipped, flipped-90, flipped-180, flipped-270.  (flipped means mirrored)


Scale/zoom factor N for xpra, Xorg or Weston. Allowed for --xpra* and --xorg: 0.25...8.0. Allowed for --weston and --weston-xwayland: 1...9.


Screen size of new X server (e.g. 800x600).

-w,  --wm [=ARG]

Provide a host window manager to container applications. (In case of --xc only openbox is provided.) Possible ARG:
host     autodetection of a host window manager.
COMMAND  command for a desired host window manager.
none     Run without a window manager. Same as --desktop.

-F,  --xfishtank

Show fish tank on new X server.

X and Wayland special configuration

--checkwindow [=ARG]

Run container until all X windows are closed. If ARG is provided, run container as long as grep can find ARG in output of xwininfo -root -children. This option helps to keep alive containers with self-forking applications like gnome-terminal or to stop endless running ones like chromium.


Disable xhost access policies on host display.

--composite [=yes|no]

Enable or disable X extension Composite. Default is yes except for --nxagent. Can cause or fix issues with some applications on nxagent.


Run new X server with display number N. Must not be already in use.


Set keyboard layout for new X server, e.g. de, us, ru. For possible LAYOUT look at /usr/share/X11/xkb/symbols.

--vt [=N]

Use vt / tty N. Without optional N search an unused tty.


Custom weston.ini for --weston and --weston-xwayland.

--xhost [=STR]

Set xhost STR on new X server (see man xhost). Without optional STR will set:  +SI:localuser:$USER . (Use with care. --xhost=+ allows access for everyone).

--xoverip [=yes|no|listentcp|socat] Connect to X over TCP network. Special

setups only, usually only enabled by x11docker itself.
yes        Use listentcp if possible, otherwise socat.
no         Use shared unix socket (general default).
listentcp  Use X option -listen tcp.
socat      Use socat to create a fake TCP connection.

--xauth [=yes|trusted|untrusted|no] Configure X cookie authentication.

Possible arguments:
yes|trusted Enable cookie authentication with trusted cookies. (General x11docker default.)
untrusted   Untrusted cookie for untrusted apps limiting access to X resources. Useful to avoid MIT-SHM with --hostdisplay.
no          Disable cookie authentication. Dangerous!

--xtest [=yes|no] Enable or disable X extension XTEST. Default is yes for

--xpra and --xvfb, no for other X servers. Needed to allow keyboard and mouse control with xpra.

Container user settings


Add container user to group GROUP.


Run X (and container user) as user USER. Default is result of $(logname). (x11docker must run as root).

--password [=WORD]

Change container user password and exit. Interactive input if argument WORD is not provided. Stored encrypted in ~/.config/x11docker/passwd.

--sudouser [=nopasswd]

Allow su and sudo for container user. Use with care, severe reduction of default x11docker security! Optionally passwordless sudo with argument nopasswd. Default password is x11docker.


Create container user U (U=name or U=uid). Default: same as host user. U can also be an unknown user id. You can specify a group id with U being user:gid. Special case: --user=RETAIN keeps image user settings.

Container capabilities

In most setups x11docker sets --cap-drop=ALL --security-opt=no-new-privileges and shows warnings if doing otherwise. Custom capabilities can be added with --cap-add=CAP after  --


Allow default container capabilities. Includes --newprivileges=yes.

--ipc [=ARG]

Without optional ARG sets run option --ipc=host (discouraged). For other possible ARG see docker run reference.

--limit [=FACTOR]

Limit CPU and RAM usage of container to currently free RAM x FACTOR and available CPUs x FACTOR. Allowed range is 0 < FACTOR <= 1. Default for --limit without optional argument FACTOR is 0.5 .

--newprivileges [=yes|no|auto]

Set or unset run option --security-opt=no-new-privileges. Default with no argument is yes. Default for most cases is no.

Container init system, elogind and DBus daemon

--dbus [=system]

Run DBus user session daemon for container command. With argument system also run a DBus system daemon. (To run a DBus system daemon rather use one of --init=systemd|openrc|runit|sysvinit )


Connect to DBus user session from host.

--init [=tini|systemd|openrc|runit|sysvinit|s6-overlay|none]

Run an init system as PID 1 in container. Solves the zombie reaping issue. By default x11docker uses tini or the similar catatonit.


Share /sys/fs/cgroup. Allows elogind in container if used with one of --init=openrc|runit|sysvinit

Container special configuration

--env VAR=value

Set custom environment variable.


Specify container name NAME.


Disable ENTRYPOINT in image to allow other commands, too


No x11docker setup in running container. Disallows several other options. See also --user=RETAIN.


Specify container runtime. Known by x11docker:
runc         Default runtime of docker.
crun         Default runtime of podman.
nvidia       Runtime for nvidia/nvidia-docker images.
sysbox-runc  Runtime for powerful root in container.


Set preferred user shell. Example: --shell=/bin/zsh


Enable support for Docker in snap.


Forward stdin of x11docker to container command.


Set working directory DIR.

Additional commands

You might need to move them to background with CMD &.


Run command CMD as root in container.


Run command CMD with user privileges in container before running image command.

--runfromhost=CMD Run host command CMD on new X server.


--build IMAGE

Build an image from a Dockerfile from x11docker repository. Example: x11docker --build x11docker/fvwm . Works for all repositories beginning with 'dockerfile' at https://github.com/mviereck?tab=repositories . Regards (only) option --backend=BACKEND.


Custom base folder for cache files.


Custom base folder for option --home.

--fallback [=yes|no]

Allow or deny fallbacks if a chosen option cannot be fulfilled. By default fallbacks are allowed.


Create application launcher with current options on desktop and exit. You can get a menu entry moving the created *.desktop file to ~/.local/share/applications


Use MobyVM (for WSL2 only that defaults to Linux Docker).


Read a set of predefined options stored in file FILE. Useful to shortcut often used option combinations.
FILE is searched in directory /etc/x11docker/preset, or in directory ~/.config/x11docker/preset.
Multiple lines in FILE are allowed.
Comment lines must begin with # .
Local presets supersede global ones in /etc .
Special case: A preset file with file name default will be applied automatically for all x11docker sessions.

Output of parseable information on stdout

Get output e.g. with: read xenv < <(x11docker --printenv x11docker/check) . Optional argument FILE allows to print the information into a file.

--printenv [=FILE]

Print variables to access new display.

--printid [=FILE]

Print container ID.

--printinfofile [=FILE]

Print path to internal x11docker info storage.

--printpid1 [=FILE]

Print host PID of container PID 1.

Verbosity options

-D,  --debug

Enable rigorous error control and show some debug output.


Show dependency check messages.

-q,  --quiet

Suppress x11docker terminal messages.

-v,  --verbose

Be verbose. Output of x11docker.log on stderr.


Be verbose with colored output.

Cleanup options (might need root permissions)


Clean up orphaned containers and cache files. Those can remain if x11docker still runs on system shutdown. Terminates currently running x11docker containers, too. Regards (only) option --backend=BACKEND.

Installation options (need root permissions)

These options might not be available in packaged versions of x11docker.


Install x11docker from current folder. Useful to install from an extracted zip file.

--update [=diff]

Download and install latest release from github.

--update-master [=diff]

Download and install latest master version. Optional argument diff shows the difference between installed and new version without installing it.


Remove x11docker from your system. Includes --cleanup. Preserves ~/.local/share/x11docker from option --home.


Before version 7.6.0 x11docker installed itself into /usr/bin. Now it installs into /usr/local/bin. Use --remove-oldprefix to remove /usr/bin installations.


Package names and further optional dependencies:

Dependencies on host

For core functionality x11docker only needs bash, an X server and one of docker, podman or nerdctl. Depending on chosen options x11docker might need some additional tools. It checks for them on startup and shows messages if some are missing.

* Most recommended: Provide image x11docker/xserver to run X or Wayland in container. The image contains all X related dependencies.

Otherwise provide on host:

* Recommended to allow security and convenience:
X servers: some of: nxagent xpra Xephyr Xorg
Tools: all of: xauth xclip xrandr xhost xinit catatonit

* Additionally for advanced GPU support: weston Xwayland xpra xdotool

Dependencies in image

No dependencies in image except for a few feature options. Most important:


OpenGL/MESA packages, collected often in mesa-utils package.
For closed source NVIDIA support look at https://github.com/mviereck/x11docker/wiki/NVIDIA-driver-support-for-docker-container

--pulseaudio: Needs pulseaudio on host and pulseaudio client libs in image.

--printer: Needs cups on host and cups client libs in image.

Exit Codes




x11docker error


Terminated by ctrl-c


Exit code of command in container


FVWM window manager:

x11docker --desktop x11docker/fvwm

Xfce desktop:

x11docker --desktop x11docker/xfce

Accelerated glxspheres:

x11docker --gpu x11docker/check glxspheres64

Kodi media center with hardware acceleration, pulseaudio sound, shared Videos folder and persistant HOME:

x11docker --gpu --pulseaudio --home --share=~/Videos erichough/kodi

Firefox with shared Downloads folder and internet access:

x11docker -I --share $HOME/Downloads -- --tmpfs /dev/shm -- jess/firefox


Written by Martin Viereck, Germany.

Reporting Bugs

Please report issues and get help at:

See Also

Further documentation at: