기술 자료

Unity Engine

Download Unity

Unity Engine

Introduction to the Headless Editor in containers

Understand how the Headless Editor (Editor) runs in a Docker container, what the Unity Editor base image provides, and what the Editor can't do without a display.
읽는 시간 5분최근 업데이트: 11일 전

Understand how the Headless Editor (Editor) runs in a Docker container, what the Unity Editor base image provides, and what the Editor can't do without a display.
The Headless Editor is a build of the Linux Editor for automated builds. In a container, it runs from an image you build on top of the base image, and it leases a Unity license from your floating license server for each job. This page explains:
  • The Editor
  • The image layers
  • How a build job runs
  • What the base image contains
  • How licensing works in containers
  • The Editor's limitations
If you're new to Docker, the Docker concepts guide explains images, containers, Dockerfiles, volumes, and tags.

Headless Editor

The Headless Editor is a build of the Linux Editor for command-line work: importing assets, running Editor scripts, and building Players. It always runs in batch mode with no graphics device, even if you don't pass
-batchmode
or
-nographics
.
Containers give your builds these benefits:
  • Every job starts from the same image, so the build environment stays the same across build agents and over time.
  • A new build agent needs only Docker. You don't install or maintain the Editor on each build agent.
  • A job can't leave files, caches, or licenses behind for the next job unless you keep them in a mounted folder.

Image layers

Unity ships only the bottom layer. You add the Editor, its modules, and your build tools, and store the result in your own registry:
  1. Unity publishes the base image,
    unity/editor-base
    , on Docker Hub. It contains Ubuntu 24.04, the Unity command-line interface (CLI), and the Editor's system prerequisites.
  2. Your Editor image's Dockerfile specifies the base image in a
    FROM
    instruction. Your Editor image adds the Headless Editor, its modules, and target tools such as FFmpeg or the Android SDK.
  3. Each build job runs a container from your Editor image with
    docker run
    .

Unity publishes the base image on Docker Hub. Your Editor image adds the Headless Editor, modules, and target tools on top of the base image, and each build job runs a container from your Editor image.

Build job lifecycle

A build job runs in the following order:
  1. The build agent starts a container from your Editor image with
    docker run
    . It mounts the project and passes the license server's address.
  2. The Editor requests a license from the floating license server and receives a lease.
  3. The Editor opens the project and reuses the
    Library
    folder from the mounted project.
  4. The Editor imports assets and runs your build method.
  5. The Editor writes the Player and logs to mounted folders.
  6. The Editor returns the license when it exits, and the container exits with the Editor's exit code. An exit code of
    0
    means success.
  7. Docker removes the container.

Sequence of a build job: the build agent starts the container, the Editor leases a license, reads the project, writes the Player and logs to mounted folders, returns the license, and Docker removes the container.

The container keeps nothing between jobs. The
Library
folder, build output, and logs survive only because the Editor writes them to mounted folders.

Base image contents

The base image is Ubuntu 24.04 with the following components:
  • The Unity CLI at
    /usr/local/bin/unity
    , which every user can run
  • The libraries that the Headless Editor loads
The image also solves several container-specific problems:

Setup

What the image does

Problem it prevents

LocaleGenerates the
en_US.UTF-8
locale and sets
LANG=en_US.UTF-8
.
The Editor reports
SystemLanguage.Unknown
, and tools such as the JDK and Gradle run in ASCII.
Licensing client runtime folderSets
XDG_RUNTIME_DIR
to a writable folder.
The licensing client fails with
Failed to initialise UDS client
.
AudioConfigures an ALSA null sink in
/etc/asound.conf
, because a container has no sound device.
The Editor's audio engine, FMOD, fails to initialize with error
60
.
FontsInstalls fallback fonts with CJK coverage: Liberation, FreeFont, and Droid Sans Fallback.Characters that no installed font covers fall back to the Editor's built-in font.
Graphics librariesInstalls libGL and Mesa, because the Editor binaries link against them.The Editor fails to load. The Headless Editor renders nothing: it uses a null graphics device.
Other runtime dependenciesInstalls Python 3 for Web builds, libxml2 for the FBX importer, ICU for .NET globalization, and CA certificates and libcurl for licensing and package downloads over TLS.Build, import, and download failures.
The base image doesn't contain the Editor, Xvfb, test tooling, or FFmpeg. It defines no user of its own and runs as root by default. Ubuntu's built-in
ubuntu
user (uid 1000) is available.

Licensing in containers

The Headless Editor activates only with a license from a Unity Licensing Server when in a container environment. Each running container leases one license when the Editor starts and returns it when the Editor exits, so the size of your license pool limits how many builds you can run at once. A license returns to the pool only when the Editor exits. If a container stops before the Editor exits, the license server reclaims the license after 15 minutes.
Named user licenses and serial-based activation don't work in a container, because those licenses bind to machine-identifying information that changes every time a container starts.

Headless Editor limitations

The Headless Editor is intended for builds and other workflows that don't require a graphical interface. It doesn't support the following:
  • Editor windows: you can't open Editor windows, and code that expects one, such as
    EditorWindow.GetWindow
    , doesn't work.
  • Rendered frames: Editor scripts that wait for a repaint or an end-of-frame callback don't progress.
  • Displays: code that enumerates screens or resolutions gets none.
  • GPU work: the Headless Editor is equivalent to running with the
    -nographics
    option, so GPU lightmapping, compute-shader-based tools, and graphics tests don't run.
  • Arm64: only Linux x86_64 hosts and containers are supported.
The Unity Test Framework runs in the Headless Editor with
-runTests
, with these limits:
  • Edit mode tests run, except tests that open windows or send GUI events. Window and GUI calls do nothing in the Headless Editor.
  • Play mode tests in the Editor advance frames with
    yield return null
    , but the Editor renders nothing.
  • A test that yields
    WaitForEndOfFrame
    fails with
    UnityTest yielded WaitForEndOfFrame, which is not evoked in batchmode
    .
  • Play mode tests run in full only in a Linux Player that you build with the Unity Test Framework.
  • Tests that need a graphics device can use
    ConditionalIgnore
    with a check for
    GraphicsDeviceType.Null
    to skip themselves.

Additional resources