How to run Unity in headless mode

Reading Time: 2 minutes

This article will cover how to set up headless Unity and execute a method using the command line interface (CLI). Headless Unity is a launch mode of the Unity game engine that allows you to run Unity in a command line interface without the need for a graphical user interface (GUI).

Why you might want to run headless unity editor

Headless unity can be useful for running automated tests, continuous integration, or other tasks that don’t require a GUI. It might not feel like you need it at the beginning, but once you set up automated tests or remotely triggered custom build processes, you will definitely appreciate it. It’s saving huge amounts of time and simplifies repetitive processes. Another benefit is fewer human errors, like forgetting to set up all the parameters correctly. Just run the pre-defined command and wait for the result.

Preparation before running unity in headless mode

Set up unity and your project

To run unity in the headless mode you need to have the “Headless Build Support” component installed in your editor instance. You can do it while installing the editor. If you want to run some processes that need runtime mode, you also need to enable the “Run in background” option in player settings.

1. Download and install Unity on your machine. Make sure to select the “Headless Build Support” component during the installation process.
2. Open the Unity editor and create a new project.
3. In the project settings, go to the “Player” tab and select the “Other Settings” subtab.
4. In the “Other Settings” section, check the “Run in background” option. This will allow Unity to continue running even when the window is not in focus.
5. Save your project and close the Unity editor.

Set up a method to be called in headless mode

There are some restrictions on which method you can run from the command line. The valid method needs to be static and parameterless. If you want to pass some parameters, the easiest way is to create a parameters file. Then you can populate the parameters before running a method and then read them in the method.

Running a method in unity headless mode

Now you can execute your method in headless mode using the command line. You can test it by calling the method manually:

Unity.exe -batchmode -nographics -executeMethod MyClass.MyMethod

To see all the arguments that unity accepts see full editor command line arguments.

Here is an example log from the successful launch of unity in headless mode

Troubleshooting

You can face some problems and exceptions trying to run your method in headless mode. Here are some examples and possible explanations.

---

executeMethod method BuildScript.BuildWebGL has 1 arguments. Only methods with 0 arguments are supported.

You’ve added arguments to the method that you want to call from the command line. Unfortunately, it’s not legal. You can only call parameterless methods.

---

executeMethod method 'BuildWebGL' in class 'BuildScript' could not be found.
Argument was -executeMethod BuildScript.BuildWebGL

The method is not marked as static. When you want to call a method from CLI, you need to mark this method as static.

Learn more about unity

If you want to learn more about unity, you might like our latest article about runtime model transformations.