Here's what you'll need:
- An Unreal Engine development image with support for GPU acceleration and a copy of the X11 runtime libraries
- A local Linux development environment configured for running containers with GPU acceleration and running an X11 server
Contents
Overview
Simpler alternative available:
This approach is far more restrictive than simply copying the Engine Installation to the host system and running it natively. In the majority of situations you will be better off following the instructions provided on the Linux Installed Builds page instead.
On Linux host systems that satisfy the requirements listed at the top of this page, it is possible to run the Unreal Editor from inside a container with full GPU acceleration and have its UI windows displayed on the host system. This facilitates a deployment strategy where the Unreal Engine runs on developers’ machines in a sandboxed environment that still allows users to interact with the Editor in the same manner as they would if it were running natively. This can be useful in scenarios where you need to bundle complex dependencies with the Editor (such as machine learning frameworks) or if you are using a custom Engine version that is updated very frequently and will benefit from the ability to rapidly deploy updates to developers’ workstations.
Key considerations
-
This approach only works on machines that satisfy the hardware and software requirements for running GPU accelerated Linux containers. By contrast, exporting Linux Installed Builds and running them natively will work on any Linux machine that is capable of running the Unreal Editor.
-
Because this approach makes use of a bind-mounted X11 socket, an X11 server must be running on the host system. Linux distributions that ship with an alternative display server protocol enabled by default (e.g. Wayland) will require additional configuration to enable an X11 user session.
-
Development container images must include the X11 runtime libraries in order for the Unreal Engine to recognise the bind-mounted X11 socket. If your container images do not include the relevant libraries then the Editor will default to offscreen rendering and no UI windows will be displayed.
Implementation guidelines
Implementation-agnostic commands
Starting a container
Irrespective of the source of development container images that is used, the following command will start a container from which the Editor can be run interactively (replace unreal-engine:latest
with the tag for your container image):
The individual arguments to the docker run command are explained below:
-
--rm
: Removes the container when it stops. -
-ti
: Starts an interactive session. -
--gpus=all
: Enables GPU access via the NVIDIA Container Toolkit. -
-v/tmp/.X11-unix:/tmp/.X11-unix:rw
: Bind-mounts the X11 socket from the host system. -
-e DISPLAY
: Propagates theDISPLAY
environment variable from the host system. -
"unreal-engine:latest"
: Replace this with the tag for your container image. -
bash
: Starts an interactive bash shell.
Once the interactive bash shell has started, you can run the UE4Editor
executable using the appropriate path for your container image. If everything is working correctly, the Unreal Editor splash screen should be displayed on the host system’s display. Once the Editor has completed loading then you can interact with it as you normally would if it were running on the host system.
Bind-mounting project directories
Any data stored in the container’s filesystem will be erased when the container is removed. To create projects that will persist, or to access existing projects, you will need to bind-mount the appropriate directories from the host filesystem.
Avoiding repeated shader recompilation
Under Linux, the Editor stores its cache for compiled assets under the directory $HOME/.config/Epic
. By default, this directory exists only inside the container filesystem and is erased when the container is removed. To ensure the data in this directory persists between container runs, you can bind-mount this directory from the host system by adding the flag "-v$HOME/.config/Epic:/home/ue4/.config/Epic"
to your docker run command.
Enabling audio support
By default, the container will not have access to the audio devices from the host system and so audio output will be disabled. If your container images include PulseAudio support then you can enable audio output by bind-mounting the PulseAudio socket from the host system using the flag "-v/run/user/$UID/pulse:/run/user/1000/pulse"
. Note that this will not work for the root user, so you will need to run the command as a non-root user as described by the Post-installation steps for Linux page of the Docker documentation.
Using container images from the ue4-docker project
The ue4-docker project supports running a sandboxed Editor using the ue4-full container image. Once you have obtained this container image then you can run containers using the commands from the Implementation-agnostic commands section.
Using container images built from custom Dockerfiles
Check out the Tips for working with the NVIDIA Container Toolkit section of the custom Dockerfile guide for instructions on enabling X11 and/or audio output support in your own container images. Once you have built your container images then you can run them using the commands from the Implementation-agnostic commands section.
Related media
This content is landing soon!
Be sure to check out the Unreal Containers Twitter feed for news about content updates.