Overview

Introduction to ue4cli

Overview

The ue4cli Python package implements a command-line tool called ue4 that provides a simplified interface to various functionality of the build system for Epic Games’ Unreal Engine 4. The primary goals of this tool are as follows:

  • Abstract away the platform-specific details of the various batch files and shell scripts scattered throughout the Engine’s source tree.
  • Provide the ability to easily generate IDE project files under Linux, where no shell integration currently exists to perform this task from outside the Editor.
  • Determine the compiler flags required to build third-party libraries for use within Engine modules. This is particularly important under macOS and Linux where symbol interposition can cause clashes between external libraries and those bundled in the ThirdParty directory of the Engine source tree, and under Linux where libraries need to build against the Engine’s bundled version of libc++.

Installation

ue4cli requires Python 3.5 or newer, and works as an interface to Unreal Engine 4.19.0 or newer.

To install ue4cli, simply run:

# This may need to be prefixed with sudo under Linux and macOS
pip3 install ue4cli

Under macOS, the old version of Mono that comes bundled with the Unreal Engine breaks when compiling .NET projects that have spaces in their paths, so you will need to install the latest version of Mono using Homebrew:

brew install mono

Unreal Engine location auto-detection

Auto-detection is most useful when you are only working with a single version of the Unreal Engine and it is installed in the default location. If you have multiple Engine installations and want to control which version is used, or are working with installations in non-default locations (such as source builds of the Engine), then you should explicitly specify a path override using the ue4 setroot command.

Windows

The default installation directory used by the Epic Games Launcher is searched for the newest installed version:

%PROGRAMFILES%\Epic Games\UE_4.*

macOS

The default installation directory used by the Epic Games Launcher is searched for the newest installed version:

/Users/Shared/Epic Games/UE_4.*

Linux

Under Debian-based distributions, the Engine’s shell integration is utilised to locate the root directory, by parsing the shortcut file:

~/.local/share/applications/UE4Editor.desktop

If this file doesn’t exist, then the command UE4Editor needs to be in the system PATH.

List of commands

Configuration Commands

These commands control the configuration of ue4cli itself.

  • ue4 clearcache

    Clears any cached data that ue4cli has stored.

  • ue4 clearroot

    Removes any previously-specified Engine root path override.

  • ue4 setroot

    Sets an Engine root path override that supersedes auto-detection.

Engine Commands

These commands relate to the currently detected or configured installation of the Unreal Engine.

  • ue4 build-target

    Build the specified target using UBT.

  • ue4 editor

    Runs the editor without an Unreal project (useful for creating new projects).

  • ue4 root

    Prints the path to the root directory of the Unreal Engine installation.

  • ue4 version

    Prints the version string of the Unreal Engine installation.

Descriptor Commands

These commands relate to an individual Unreal project or plugin, and will look for a .uproject or .uplugin file located in the current working directory. (Note that some commands only support projects, not plugins.)

  • ue4 build

    Builds the Editor modules for the Unreal project or plugin.

  • ue4 clean

    Cleans build artifacts for the Unreal project or plugin.

  • ue4 gen

    Generates IDE project files for the Unreal project.

  • ue4 package

    Packages a build of the Unreal project or plugin in the current directory.

  • ue4 run

    Runs the Editor for the Unreal project.

  • ue4 test

    Runs automation tests for the Unreal project.

Library Commands

These commands are for developers compiling modules that need to build against UE4-bundled third-party libraries for purposes of interoperability with the Engine.

  • ue4 cmakeflags

    Prints the CMake flags for building against the specified libraries.

  • ue4 cxxflags

    Prints the compiler flags for building against the specified libraries.

  • ue4 defines

    Prints the preprocessor definitions for the specified libraries.

  • ue4 includedirs

    Prints the header include directories for the specified libraries.

  • ue4 ldflags

    Prints the linker flags for building against the specified libraries.

  • ue4 libfiles

    Prints the library files for the specified libraries.

  • ue4 libs

    Lists the third-party libraries bundled with the Unreal Engine installation.

Automation Commands

These commands relate to Unreal’s automation system. Unless explicitly specified, the platform and project file path arguments will be automatically generated when invoking RunUAT.

  • ue4 uat

    Invokes RunUAT with the specified arguments.