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 or .
-batchmode-nographicsContainers 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:
- Unity publishes the base image, , on Docker Hub. It contains Ubuntu 24.04, the Unity command-line interface (CLI), and the Editor's system prerequisites.
unity/editor-base - Your Editor image's Dockerfile specifies the base image in a instruction. Your Editor image adds the Headless Editor, its modules, and target tools such as FFmpeg or the Android SDK.
FROM - 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:
- The build agent starts a container from your Editor image with . It mounts the project and passes the license server's address.
docker run - The Editor requests a license from the floating license server and receives a lease.
- The Editor opens the project and reuses the folder from the mounted project.
Library - The Editor imports assets and runs your build method.
- The Editor writes the Player and logs to mounted folders.
- The Editor returns the license when it exits, and the container exits with the Editor's exit code. An exit code of means success.
0 - 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 folder, build output, and logs survive only because the Editor writes them to mounted folders.
LibraryBase image contents
The base image is Ubuntu 24.04 with the following components:
- The Unity CLI at , which every user can run
/usr/local/bin/unity - The libraries that the Headless Editor loads
The image also solves several container-specific problems:
Setup | What the image does | Problem it prevents |
|---|---|---|
| Locale | Generates the | The Editor reports |
| Licensing client runtime folder | Sets | The licensing client fails with |
| Audio | Configures an ALSA null sink in | The Editor's audio engine, FMOD, fails to initialize with error |
| Fonts | Installs 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 libraries | Installs 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 dependencies | Installs 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 user (uid 1000) is available.
ubuntuLicensing 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 , doesn't work.
EditorWindow.GetWindow - 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 option, so GPU lightmapping, compute-shader-based tools, and graphics tests don't run.
-nographics - Arm64: only Linux x86_64 hosts and containers are supported.
The Unity Test Framework runs in the Headless Editor with , with these limits:
-runTests- 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 , but the Editor renders nothing.
yield return null - A test that yields fails with
WaitForEndOfFrame.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 with a check for
ConditionalIgnoreto skip themselves.GraphicsDeviceType.Null