Advanced build options
- General options
- Performing a dry run
- Specifying a custom namespace for the image tags
- Specifying Git credentials
- Building a custom version of the Unreal Engine
- Pulling a prebuilt version of the
- Excluding Engine components to reduce the final image size
- Enabling system resource monitoring during builds
- Windows-specific options
- Linux-specific options
Performing a dry run
If you would like to see what
docker build commands will be run without actually building anything, you can specify the
--dry-run flag when invoking the ue4-docker build command. Execution will proceed as normal, but no Git credentials will be requested and all
docker build commands will be printed to standard output instead of being executed as child processes.
Specifying a custom namespace for the image tags
If you would like to override the default
adamrehn/ prefix that is used when generating the tags for all built images, you can do so by specifying a custom value using the
UE4DOCKER_TAG_NAMESPACE environment variable. Note that this setting does not effect the ue4-build-prerequisites image, which always retains its default name in order to maintain compatibility with the prebuilt version from Docker Hub.
Specifying Git credentials
The ue4-docker build command supports three methods for specifying the credentials that will be used to clone the UE4 Git repository:
Command-line arguments: the
-passwordcommand-line arguments can be used to specify the username and password, respectively.
Environment variables: the
UE4DOCKER_PASSWORDenvironment variables can be used to specify the username and password, respectively. Note that credentials specified via command-line arguments will take precedence over values defined in environment variables.
Standard input: if either the username or password has not been specified via a command-line argument or environment variable then the build command will prompt the user to enter the credential(s) for which values have not already been specified.
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.)
Building a custom version of the Unreal Engine
If you would like to build a custom version of UE4 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
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
Pulling a prebuilt version of the
If you would like to pull the prebuilt version of the ue4-build-prerequisites image from Docker Hub instead of building it locally, simply specify the
--pull-prerequisites flag when invoking the ue4-docker build command. This is primarily useful when building images under versions of Windows Server Core prior to Windows Server 2019, since using the prebuilt image allows you to avoid copying the required DLL files from Windows 10. Note however that prebuilt versions of the image are available only for LTSC versions of Windows, not for SAC versions.
Excluding Engine components to reduce the final image size
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:
ddc: disables building the DDC for the Engine. This significantly speeds up building the Engine itself but results in far longer cook times when subsequently packaging Unreal projects.
debug: removes all debug symbols from the built images. (When building Windows containers the files are actually truncated instead of removed, so they still exist but have a size of zero bytes. This is done for compatibility reasons.)
templates: removes the template projects and samples that ship with the Engine.
You can specify the
--exclude flag multiple times to exclude as many components as you like. For example:
Enabling system resource monitoring during builds
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:
Specifying the Windows Server Core base image tag
-basetag flag controls how the ue4-build-prerequisites image is built and tagged, which has a flow-on effect to all of the other images. If you are building multiple related images over separate invocations of the build command (e.g. building the ue4-source image in one command and then subsequently building the ue4-minimal image in another command), be sure to specify the same
-basetag flag each time to avoid unintentionally building two sets of unrelated images with different configurations.
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.
Specifying the isolation mode under Windows
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.
Specifying the directory from which to copy required Windows DLL files
By default, DLL files are copied from
%SystemRoot%\System32. However, when building container images with an older kernel version than the host, the copied DLL files will be too new and the container OS will refuse to load them. A custom directory containing the correct DLL files for the container kernel version can be specified via the
-dlldir=DIR flag when invoking the build command.
Keeping or excluding Installed Build debug symbols under Windows
Excluding debug symbols is necessary under some versions of Docker as a workaround for a bug that limits the amount of data that a
COPY directive can process to 8GB. See this section of the Troubleshooting Build Issues page for further details on this issue.
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.
Building Linux container images under Windows
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.
Enabling CUDA support for GPU-enabled Linux images
--cuda flag controls how the ue4-build-prerequisites image is built and tagged, which has a flow-on effect to all of the other images. If you are building multiple related images over separate invocations of the build command (e.g. building the ue4-source image in one command and then subsequently building the ue4-minimal image in another command), be sure to specify the same
--cuda flag each time to avoid unintentionally building two sets of unrelated images with different configurations.
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 18.04 image tags for the nvidia/cudagl base image.