ue4-docker user manual

The ue4-docker build command supports three methods for specifying the credentials that will be used to clone the Unreal Engine Git repository:

Note that the username and password are handled independently, which means you can use different methods to specify the two credentials (e.g. username specified via command-line argument and password supplied via standard input.)

Users who have enabled Two-Factor Authentication (2FA) for their GitHub account will need to generate a personal access token and use that in place of their password.

If you would like to build a custom version of Unreal Engine rather than one of the official releases from Epic, you can specify "custom" as the release string and specify the Git repository and branch/tag that should be cloned. When building a custom Engine version, both the repository URL and branch/tag must be specified:

If you would like to build a custom version of Unreal Engine rather than one of the official releases from Epic, you can specify "custom" as the release string and specify the Git repository and branch/tag that should be cloned. When building a custom Engine version, both the repository URL and branch/tag must be specified:

This will produce images tagged adamrehn/ue4-source:custom, adamrehn/ue4-minimal:custom, etc.

If you are performing multiple custom builds and wish to differentiate between them, it is recommended to also specify a name for the custom build:

This will produce images tagged adamrehn/ue4-source:my-custom-build, adamrehn/ue4-minimal:my-custom-build, etc.

Starting in ue4-docker version 0.0.30, you can use the --exclude flag when running the ue4-docker build command to specify that certain Engine components should be excluded from the ue4-minimal and ue4-full images. The following components can be excluded:

You can specify the --exclude flag multiple times to exclude as many components as you like. For example:

Starting in ue4-docker version 0.0.46, you can use the --monitor flag to enable a background thread that will log information about system resource usage (available disk space and memory, CPU usage, etc.) at intervals during the build. You can also use the -interval flag to override the default interval of 20 seconds:

Since ue4-docker version 0.0.78, the ue4-docker build command supports a flag called -layout that allows the generated Dockerfiles to be exported to a filesystem directory instead of being built. In addition, version 0.0.80 of ue4-docker added support for a flag called --combine that allows you to combine multiple generated Dockerfiles into a single Dockerfile that performs a multi-stage build. You can use these flags like so:

Exporting Dockerfiles is useful for debugging or contributing to the development of ue4-docker itself. You can also use the generated Dockerfiles to build container images independently of ue4-docker, but only under the following circumstances:

Since ue4-docker version 0.0.78, the ue4-docker build command supports a flag called --opt that allows users to directly set the context values passed to the underlying Jinja templating engine used to generate Dockerfiles. Some of these options (such as source_mode) can only be used when exporting generated Dockerfiles, whereas others can be used with the regular ue4-docker build process. Note that incorrect use of these options can break build behaviour, so only use an option if you have read through both this documentation and the ue4-docker source code itself and understand exactly what that option does. The following options are supported as of the latest version of ue4-docker:

By default, Windows container images are based on the Windows Server Core release that best matches the version of the host operating system. However, Windows containers cannot run a newer kernel version than that of the host operating system, rendering the latest images unusable under older versions of Windows 10 and Windows Server. (See the Windows Container Version Compatibility page for a table detailing which configurations are supported.)

If you are building images with the intention of subsequently running them under an older version of Windows 10 or Windows Server, you will need to build images based on the same kernel version as the target system (or older.) The kernel version can be specified by providing the appropriate base OS image tag via the -basetag=TAG flag when invoking the build command:

For a list of supported base image tags, see the Windows Server Core base image on Docker Hub.

The isolation mode can be explicitly specified via the -isolation=MODE flag when invoking the build command. Valid values are process (supported under Windows Server and Windows 10 version 1809 or newer) or hyperv (supported under both Windows 10 and Windows Server.) If you do not explicitly specify an isolation mode then the appropriate default for the host system will be used.

Prior to version 0.0.30, ue4-docker defaulted to truncating all .pdb files when building the Installed Build for the ue4-minimal Windows image. This was done primarily to address the bug described in the warning alert above, and also had the benefit of reducing the overall size of the built container images. However, if you required the debug symbols for producing debuggable builds, you had to opt to retain all .pdb files by specifying the --keep-debug flag when invoking the build command. (This flag was removed in ue4-docker version 0.0.30, when the default behaviour was changed and replaced with a more generic, cross-platform approach.)

Since ue4-docker version 0.0.30, debug symbols are kept intact by default, and can be removed by using the --exclude debug flag as described in the section Excluding Engine components to reduce the final image size.

By default, Windows container images are built when running the build command under Windows. To build Linux container images instead, simply specify the --linux flag when invoking the build command.

By default, the Linux images built by ue4-docker support hardware-accelerated OpenGL when run via the NVIDIA Container Toolkit. If you would like CUDA support in addition to OpenGL support, simply specify the --cuda flag when invoking the build command.

You can also control the version of the CUDA base image that is used by appending a version number when specifying the --cuda flag, as demonstrated below:

For a list of supported CUDA versions, see the list of Ubuntu 22.04 image tags for the nvidia/cuda base image.

This indicates an underlying network or proxy server issue outside ue4-docker itself that you will need to troubleshoot. You can use the ue4-docker diagnostics command to test container network connectivity during the troubleshooting process. Here are some steps to try:

This typically indicates that the firewall on the host system is blocking connections from the Docker container, preventing it from retrieving the Git credentials supplied by the build command. This is particularly noticeable under a clean installation of Windows Server, which blocks connections from other subnets by default. The firewall will need to be configured appropriately to allow the connection, or else temporarily disabled. (Under Windows Server, the ue4-docker setup command can configure the firewall rule for you automatically.)

This is typically caused by insufficient available disk space. To fix this, simply free up some disk space and run the build again. Running docker system prune can be helpful for freeing up space occupied by untagged images. Note that restarting the Docker daemon and/or rebooting the host system may also help, since some versions of Docker have a bug that results in the amount of required disk space slowly increasing as more and more builds are run.

Assuming you haven’t actually run out of disk space, this means that the maximum Docker image size has not been configured correctly.

Some versions of Docker contain one or more of a series of separate but related bugs that prevent the creation of filesystem layers which are 8GiB in size or larger:

#37581 was fixed in Docker CE 18.09.0, whilst #40444 was fixed in Docker CE 20.10.0.

If you are using a version of Docker that contains one of these bugs then you will need to exclude debug symbols, which reduces the size of the Installed Build below the 8GiB threshold. If debug symbols are required then it will be necessary to upgrade or downgrade to a version of Docker that does not suffer from the 8GiB size limit issue (although finding such a version under Windows may prove quite difficult.)

This is typically caused by the download of the Unreal Engine’s toolchain archive from the Epic Games CDN becoming corrupted and failing to extract correctly. This issue can occur both inside containers and when running directly on a host system, and the fix is to simply delete the corrupted files and try again:

This is a known compatibility issue that affects Unreal Engine 5.0.0 through to Unreal Engine 5.0.3 when running under Ubuntu 22.04 or newer. In order to build Unreal Engine 5.0 in a Linux container, you will need to use an Ubuntu 20.04 base image by specifying the flags -basetag ubuntu20.04.

Microsoft issued a security update in February 2020 that broke container compatibility for all versions of Windows Server and caused 32-bit applications to fail silently when run. The issue is resolved by ensuring that both the host system and the container image are using versions of Windows that incorporate the fix:

Recent versions of Docker under Windows may sometimes encounter the error hcsshim: timeout waiting for notification extra info when building or running Windows containers. This is a known issue when using Windows containers in Hyper-V isolation mode. At the time of writing, Microsoft have stated that they are aware of the problem, but an official fix is yet to be released.

As a workaround until a proper fix is issued, it seems that altering the memory limit for containers between subsequent invocations of the docker command can reduce the frequency with which this error occurs. (Changing the memory limit when using Hyper-V isolation likely forces Docker to provision a new Hyper-V VM, preventing it from re-using an existing one that has become unresponsive.) Please note that this workaround has been devised based on my own testing under Windows 10 and may not hold true when using Hyper-V isolation under Windows Server.

To enable the workaround, specify the --random-memory flag when invoking the build command. This will set the container memory limit to a random value between 10GB and 12GB when the build command starts. If a build fails with the hcsshim timeout error, simply re-run the build command and in most cases the build will continue successfully, even if only for a short while. Restarting the Docker daemon may also help.

Note that some older versions of UnrealBuildTool will crash with an error stating "The process cannot access the file because it is being used by another process" when using a memory limit that is not a multiple of 4GB. If this happens, simply run the build command again with an appropriate memory limit (e.g. -m 8GB or -m 12GB.) If the access error occurs even when using an appropriate memory limit, this likely indicates that Windows is unable to allocate the full amount of memory to the container. Rebooting the host system may help to alleviate this issue.

This error is shown in two situations:

This is a known issue when the host system is running an older kernel version than the container image. Just like in the case of "The operating system of the container does not match the operating system of the host" error mentioned above, you will need to build the images using the same kernel version as the host system or older. See Specifying the Windows Server Core base image tag for details on specifying the correct kernel version when building Windows container images.

This is a known bug in some older versions of UnrealBuildTool when using a memory limit that is not a multiple of 4GB. To alleviate this issue, specify an appropriate memory limit override (e.g. -m 8GB or -m 12GB.) For more details on this issue, see the last paragraph of the hcsshim timeout issues section.

This is a known bug in some versions of Visual Studio which only appears to occur intermittently. The simplest fix is to simply reboot the host system and then re-run the build command. Insufficient available memory may also contribute to triggering this bug. Note that a linker wrapper was added in Unreal Engine 4.24.0 to automatically retry link operations in the event that this bug occurs, so it shouldn’t be an issue when building version 4.24.0 or newer.

This error typically occurs when the Windows pagefile size is not large enough. As stated in the Troubleshooting build issues, there is currently no exposed mechanism to control the pagefile size for containers running in Hyper-V isolation mode. However, containers running in process isolation mode will use the pagefile settings of the host system. When using process isolation mode, this error can be resolved by increasing the pagefile size on the host system. (Note that the host system will usually need to be rebooted for the updated pagefile settings to take effect.)

The paths associated with Windows bind-mounted directories inside Hyper-V isolation mode VMs can cause issues for certain build tools, including UnrealBuildTool and CMake. As a result, building Unreal projects located in Windows bind-mounted directories is not advised when using Hyper-V isolation mode. The solution is to copy the Unreal project to a temporary directory within the container’s filesystem and build it there, copying any produced build artifacts back to the host system via the bind-mounted directory as necessary.

Some versions of Docker contain one or more of a series of separate but related bugs that prevent the creation of filesystem layers which are 8GiB in size or larger. This also causes COPY directives to fail when copying data in excess of 8GiB in size, breaking Dockerfile steps during the creation of Installed Builds that contain debug symbols.

This diagnostic tests whether the host system’s Docker daemon suffers from this issue, by attempting to build a simple test Dockerfile with an 8GiB filesystem layer:

This diagnostic tests whether running containers are able to access the internet, resolve DNS entries, and download remote files:

Installed Builds of Unreal Engine can be exported to the host system starting with version 4.21.0. Once you have built either the ue4-minimal or ue4-full image for the UE4 version that you want to export, you can export it to the host system like so:

The Conan wrapper packages generated by conan-ue4cli can be exported from the ue4-full image to the local Conan package cache on the host system like so:

Conan will need to be installed on the host system for this to work. To use the exported packages for development on the host system, you will also need to generate the accompanying profile-wide packages by running the command:

This will require both ue4cli and conan-ue4cli to be installed on the host system.