Skip to main content

UEFS

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.

Benefits

  • 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 --persistent for 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.0 into 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:\UnrealEngine if that's your thing.

Examples

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