ue4-docker: container images for building and testing Unreal Engine 4

What the package produces and what problem it solves

The ue4-docker Python package contains a set of Dockerfiles and accompanying build infrastructure that allows you to build Docker images for Epic Games' Unreal Engine. The images also incorporate the infrastructure from ue4cli, conan-ue4cli and ue4-ci-helpers, to facilitate a wide variety of use cases.

The problem being solved is the one every Unreal Engine team hits sooner or later. Building the engine is slow, it depends on a specific toolchain and a specific platform configuration, and the result differs between a developer's machine and a build server. Putting it in a container makes the environment reproducible, and it means the engine is compiled once and reused rather than rebuilt on every machine.

The three use cases the README links out for are the ones the containers were built for: continuous integration, pixel streaming, and Unreal Engine powered microservices. The community hub at unrealcontainers.com is presented as the place to start, with implementation-agnostic information on running Unreal Engine inside Docker containers, and the project-specific documentation living separately.

The key features list makes the scope concrete. The six most recent versions of Unreal Engine are supported, currently 4.27 and newer. Both Windows containers and Linux containers are supported. Building and packaging Unreal Engine projects is supported. Running automation tests is supported. And running built Unreal Engine projects with offscreen rendering is supported via the NVIDIA Container Toolkit under Linux.

That last item is the one that makes these images more than a compiler wrapper. A headless Unreal project running in a container with offscreen rendering is a server-rendered frame, which is what pixel streaming and some rendering-as-a-service setups need.

The package layout and how the images are generated

The pyproject.toml describes a package that is not the images themselves but the machinery that builds them.

The name is ue4-docker, the version is 0.0.124, and the console entry point is declared as ue4-docker mapped to ue4docker:main. That naming tells you the images are produced on demand rather than published as a fixed set, which is the right design for engine versions that change and for platforms that differ.

The dependencies are ordinary Python packages rather than anything Unreal-specific: colorama for Windows terminal colours, docker 6.1.0 or newer for talking to the daemon, humanfriendly for formatting, Jinja2 for templating the Dockerfiles, packaging for version handling, psutil for process and system inspection, and termcolor for output colouring.

Jinja2 is the interesting one, because it explains how a set of Dockerfiles can cover six engine versions and two operating systems without being a maintenance nightmare. The Dockerfiles are templates, and the build infrastructure renders them with the specifics for the engine version and platform you asked for.

The package data section confirms the shape of the output. The templates live in a dockerfiles/ directory, and the patterns are dockerfiles/*/*/.dockerignore for the per-image ignore files, dockerfiles/diagnostics/*/*/* for the diagnostic images, and dockerfiles/*/*/* for the general case. Two levels of wildcards are the engine version and the platform.

The repository layout matches: src/ for the package source, docs/ for the documentation, resources/ for images and templates, test-suite/ for the tests, and a pyproject.toml that declares the whole thing with a setuptools backend. The classifiers call the development status Production/Stable, and the topic is Software Development with Build Tools.

There are two authors listed, Adam Rehn and Marat Radchenko, and the copyright runs from 2018 to 2024 under the MIT licence, with the Docker and Unreal trademarks explicitly disclaimed.

Supported engine versions and the sibling projects it builds on

The support matrix is stated in one line and it is the number that decides whether you can use this.

The six most recent versions of Unreal Engine are supported, currently 4.27 and newer. That is a moving target rather than a fixed list, and it is defined in terms of the engine's own numbering rather than by container image tags.

The three companion projects are worth understanding individually, because they divide the work differently.

ue4cli is the command line interface for Unreal Engine, the tool that lets you build a project from a terminal rather than through the editor's interface. conan-ue4cli wraps it with Conan, the C and C++ package manager, which is how the third-party native dependencies a project needs get resolved into the image. ue4-ci-helpers holds the helpers aimed specifically at continuous integration, the pieces that turn a build into something a pipeline can consume.

That layering is the reason the package can support both Windows and Linux containers. The build recipe is the same shape on both platforms and the platform-specific part is what the templates vary, which is a much smaller thing to maintain than two separate build systems.

The window of six supported versions also tells you something about the maintenance model. An engine version that falls out of the window is not going to keep receiving image updates, which is fine if you are on a current version and a problem if you are pinned to an old one for a shipped project.

What you get in a container, and what it costs

Two things about the images are worth being concrete about before you adopt them.

The first is size. An Unreal Engine container contains the engine source or a built engine, the toolchain, the build tools and usually a set of platform SDKs. These are large images, and the disk and network cost of pulling one is real. Whether that matters depends on where you run them: a build server that pulls once and caches is fine, a pipeline that pulls on every job is not, and the caching behaviour of your CI system is the thing to check.

The second is that a containerised engine build is still an engine build. The first compilation of Unreal Engine from source takes hours, and the images exist partly so that you do that once rather than on every machine. Whether a given image ships with a prebuilt engine or builds it during the image build is the difference between a fast pull and a slow one, and it is worth knowing which you are getting before you wire it into a pipeline.

The offscreen rendering support is the third thing. Running a built project with offscreen rendering needs the NVIDIA Container Toolkit, which is a host-level installation and a GPU passthrough configuration. On a machine without it the image still builds and runs automation tests, but it cannot render, and the difference shows up as a failure at the point where you expected a frame.

The README also distinguishes the licence of this project from the licence of the software inside it. The project is MIT, and Unreal and its logo are Epic Games' trademarks or registered trademarks, with the same disclaimer for Docker and its logo. The engine's own licence is what governs your use of the images, and that is a conversation with Epic rather than with this repository.

This project against a self-managed build server and against a generic CI image

Two comparisons make the choice clearer.

The first is against running the engine builds on dedicated build machines, which is what large studios have traditionally done. The difference in approach is where the environment lives. A build machine is a machine you administer, with a specific OS image, specific toolchain versions and a maintenance schedule. A container is an image you build once and run anywhere that has a Docker daemon and, on Linux, the right GPU configuration.

The advantage is not speed, it is reproducibility and onboarding. A new engineer or a new CI runner gets the same environment without a ticket to infrastructure. The cost is the images are large, the Docker daemon is a privileged service on the host, and you have to learn the template system rather than configuring a machine by hand.

The second comparison is against a generic CI image with the Unreal Engine installed by a startup script. The difference in approach is that a startup script runs on every job, whereas a prebuilt image pays that cost once. For an engine build, where the setup is long and the compilation is long, that difference dominates.

There is also the question of what else the image can do, which is where this project distinguishes itself from a plain build image. Automation tests running inside the same image as the build, and built projects running with offscreen rendering, mean the same environment covers the whole pipeline from compilation to verification to execution. A generic CI image that can compile rarely can also run the result with a GPU, and certainly does not do both from the same base.

So the case for this project is strongest for a team that builds and then verifies Unreal projects automatically, and where the same image can serve as the developer environment and the CI environment.

Editorial conclusion

Adopt ue4-docker when you need reproducible Unreal Engine build environments, on Linux or Windows, whether for continuous integration or for running automation tests on the same image your developers use. Do not expect the images to be small, since they contain the engine and its toolchain. Verify first that your engine version is one of the six supported, that the Linux images have the NVIDIA Container Toolkit available if you want offscreen rendering, and that your organisation is comfortable with the engine's licensing terms, which are separate from this project's MIT licence.

Frequently asked questions

Official sources

1. adamrehn/ue4-docker on GitHub
2. License: MIT
3. Project website
4. README
5. Releases