Getting started with UEFS

UEFS allows you to package up Unreal Engine and instantly use it on every computer in your organisation. All changes to the engine folder are done with copy-on-write, so restoring the engine to it’s original state is as easy as re-mounting the package. This quickstart guide will show you how to set up UEFS in your team or organisation.

What you need

To do everything we’re going to do in this guide, you’ll need the following already set up:

• A container registry. This can be an external registry like Docker Hub; even a public container registry. We’re not going to push anything to the external registry except for a little bit of metadata, so it doesn’t even need to be private.
• A network share with plenty of space. We’re going to store all our Unreal Engine versions on this network share. If you’re doing Windows and macOS, you’ll probably need about 200GB per Unreal Engine version; more if you’re building custom engines with console support.

Install UEFS and Dokany on every machine

On every machine that you want to use Unreal Engine, you’ll need to install:

• UEFS. Installing this depends on your platform:
  • For Windows, you’ll have to download the package and install it via Chocolatey. We’re still waiting on UEFS to go through the review queue, so to get the latest functionality ou’ll need to download the UEFS package from GitLab and then install it via Chocolatey by running the following command from an Administrative Command Prompt in the folder that contains the downloaded .nupkg file: choco install -y --pre uefs -s .
  • For macOS, run the following from a terminal. You’ll be prompted for your password as this script will install the UEFS service: curl -L -o - https://src.redpoint.games/redpointgames/uefs/-/raw/main/macos/install.sh | bash -
• Dokany. On Windows this allows you to instantly start Unreal Engine without downloading the full package first. Grab the x64 MSI from the Dokany releases page and install it. You might have to restart the computer afterwards.

Package up Unreal Engine

You can package up any version of Unreal Engine; whether it’s installed from the launcher or custom versions you’ve built with BuildGraph.

You might want to package up the launcher version in academic or enterprise scenarios so you don’t have to install and download Unreal Engine through the Epic Games Launcher on every machine. Plus using UEFS means you don’t actually have to send the entire Unreal Engine install over the network to every computer ahead-of-time; data will be fetched from the network share when it’s used for the first time on each computer.

If you’re packaging up Unreal Engine from the launcher you’d create a package with a command like this:

If you’re packaging up the macOS version, you’d run a command like this:

If you’re packaging up a custom engine version, just set the directory to where the custom engine build is located, and set the extension of the package based on the platform it was built for.

Once you’ve created the package, you’ll want to create the hash. It’s faster to create the hash locally and then copy both the package file and the hash file to the network share, rather than trying to hash it on the network share.

Generate the hash file with a command like this. You’ll need to do it for both the Windows and macOS packages if you’re packaging up both:

Copy the files to the network share

Now that you’ve packaged up Unreal Engine, you’ll have two or more of the following files:

• 5.0.3-launcher.vhd
• 5.0.3-launcher.vhd.digest
• 5.0.3-launcher.sparseimage
• 5.0.3-launcher.sparseimage.digest

Copy these files to the network share.

Register the Unreal Engine packages with the container registry

We’re now going to upload a reference to the container registry. When computers look up the package in the container registry, they’ll see the reference which will then point to the network share location.

You can register a package for Windows like so:

You can register a package for macOS with the following command. Note that on every macOS machine you’ll need to set up an automatic mount to mount the network share at /Users/Shared/NetworkShare. You can pick any path you want, but it has to be the same on every machine and match the path you’re putting in the registry.

Clean up any local files

If you downloaded the engine through the launcher to package it up, you don’t need the launcher installed version any more. You can delete it.

Now that you’ve copied the packages to the network share, you can delete those as well.

Instantly run Unreal Engine on Windows

Now it’s time for magic. On any machine on the network, persistently mount the package with:

You can pick any directory you want; we’re just picking the usual directory path since that’s what a developer would expect.

If you’ve installed Dokany on Windows, this command will be instant - it won’t actually download the package. But if you open C:\Program Files\Epic Games\UE_5.0 in File Explorer, you’ll see all of the files there. Everything is being fetched on-demand from the network share and cached locally after first use.

To test instant launch, run C:\Program Files\Epic Games\UE_5.0\Engine\Binaries\Win64\UnrealEditor.exe from either File Explorer or the Command Prompt. The first launch will be slightly slower than a local install as it’s fetching data from the network share, but subsequent launches will be as fast as a full local install.

As an added bonus, Unreal Engine installs deployed this way take up a fraction of the normal disk space. Typically you can expect to see disk usage around 5 GB instead of 100 GB.

Run Unreal Engine on macOS

macOS doesn’t support instantly launching Unreal Engine yet, so you’ll have to wait until the full package is pulled from the network share. It’s otherwise pretty similar to Windows:

Updating Unreal Engine

Let’s say you want to update everyone to 5.0.4 or you release a new version of your custom engine build. How should you go about sending this update to everyone?

1. Make your package as usual, but make sure you give it a unique new name like 5.0.4-launcher.vhd. Don’t re-use the same name or same path on a network share, as this will confuse on-demand data fetching on Windows!
2. Push the reference to the same tag on the package registry with the new path like --ref \\NETWORKSHARE\FolderWithUnrealPackages\5.0.4-launcher.vhd.
3. Unmount and re-mount the tag on each machine. At some point we’ll make UEFS automatically check the registry again on startup for persistent mounts, but for now you need to uefs unmount --dir ... and then uefs mount ... again, probably in some kind of script you run on every machine on startup.

Other tips and tricks

If you’re using UEFS on a build server, you’ll probably want to mount and unmount at paths unique to each job so you can run builds in parallel. When you run uefs mount and uefs list, it’ll give you a unique ID for the mount that you can use with uefs unmount --id ... so you won’t collide with other mounts.

I’d recommend using UEFS with the Unreal Engine Scripts as these will automatically handle using Unreal Engine from UEFS; just pass -Engine uefs:registry.example.com/unreal-engine:5.0 and the scripts will do the rest.

Closing thoughts

Hopefully this is a good enough guide on how to start using UEFS inside your team. If you’ve got any questions, send me a message on Mastodon.