Package and use self-contained Unreal Engine installs on Windows, macOS and Docker.
UEFS is a packaging system to store and mount Unreal Engine without having to extract it or copy individual files. It speeds up installation on Windows, macOS and Docker containers since it avoids the filesystem overhead of copying the hundreds of thousands of files that make up a typical Unreal Engine installation.
- There's no lengthy extraction process because packages are disk images mounted directly by the OS (VHDs on Windows and sparse images on macOS).
- There's no lengthy download process on Windows if you install Dokany. UEFS will fetch the package data on-demand as files are accessed inside mount paths, with almost no I/O performance loss. This means you can start Unreal Engine instantly, and the amount of disk space used can be as little as 5% of the full package size.
- Packages can be versioned via container registries, so when your build servers mount Unreal Engine via a tag like
gitlab.com/company/unrealengine:5.0, they'll automatically pull the latest version if needed.
Note: Despite their name, container registries can be used to store any kind of data, which is how we store UEFS packages in them. UEFS packages are not Docker images even though we use container registries to version them.
- Because Unreal Engine is instanced per mount point, you can run multiple builds in parallel without dealing with the dreaded global mutex that would otherwise prevent multiple AutomationTool instances from running. This means you can maximize your throughput on build servers even more so than only using BuildGraph.
- You can tell the mount to track the launch process with
--track-parent, which is great for build scripts because the mount will always be unmounted once the build script finishes. The Unreal Engine Scripts have already been updated with support for UEFS tags.
- You can tell a mount to be persistent across system reboots with
--persistentfor developer use cases. For example, if you have a custom engine for your company, you can package it up with UEFS and then every developer can pull it and mount it persistently with
uefs mount --tag yourregistry.com/company/unrealengine-custom:5.0 --persistent --dir C:\UnrealEngine.
- It makes pushing out launcher builds (the ones Epic provides) to your build servers much easier, since you just package
C:\Program Files\Epic Games\UE_5.0into a package, push it to the container registry, and then every build server can pull it from the tag alone.
- It provides a Docker volume plugin, which means you can add UEFS packages to your Windows Docker containers and then have them mounted inside the container with
docker ... --mount type=volume,volume-driver=uefs,volume-opt=path=C:\unreal-5.0.vhd,target=C:\UnrealEngineif that's your thing.
Creating a package
# Windows uefs build --dir "C:\Program Files\Epic Games\UE_5.0" --pkg 5.0.3-launcher.vhd # macOS uefs build --dir "/Users/Shared/Epic Games/UE_5.0" --pkg 5.0.3-launcher.sparseimage
Pushing to a registry
# You can push the Windows and macOS versions to the same tag and they will both exist at that tag. uefs push --tag registry.gitlab.com/company/repo/unreal-engine:5.0 --pkg 5.0.3-launcher.vhd uefs push --tag registry.gitlab.com/company/repo/unreal-engine:5.0 --pkg 5.0.3-launcher.sparseimage # You can also push references instead of uploading the packages to the registry. i.e. you want to store the packages on a Windows share and just use the container registry for versioning (if the container registry is on the Internet). uefs push --tag registry.gitlab.com/company/repo/unreal-engine:5.0 --pkg 5.0.3-launcher.vhd --ref \\COMPUTER\Share\5.0.3-launcher.vhd uefs push --tag registry.gitlab.com/company/repo/unreal-engine:5.0 --pkg 5.0.3-launcher.sparseimage --ref /Some/Path/To/Mounted/Share/5.0.3-launcher.sparseimage
Using a package
# Mounting by file on Windows uefs mount --pkg 5.0.3-launcher.vhd --dir C:\UnrealEngine # Mounting by file on macOS uefs mount --pkg 5.0.3-launcher.sparseimage --dir /Users/Shared/UE # Mounting by registry tag uefs mount --pkg registry.gitlab.com/company/repo/unreal-engine:5.0 --dir C:\UnrealEngine # Mounting by registry tag until the current process exits uefs mount --pkg registry.gitlab.com/company/repo/unreal-engine:5.0 --dir C:\UnrealEngine --track-parent # Mounting by registry tag and persist across reboots uefs mount --pkg registry.gitlab.com/company/repo/unreal-engine:5.0 --dir C:\UnrealEngine --persist
Creating and using with Docker (Windows containers)
# After adding mypkg.vhd to a container image docker run --rm --isolation=process -i --mount type=volume,volume-driver=uefs,volume-opt=path=C:\unreal-5.0.vhd,target=C:\mypkg.vhd my-image-name