Unity is usually launched by double-clicking its icon from the desktop. However, it is also possible to run it from the command line (from the macOS Terminal or the Windows Command Prompt). When launched in this way, Unity can receive commands and information on startup, which can be very useful for test suites, automated builds and other production tasks.
On macOS, type the following into the Terminal to launch Unity:
/Applications/Unity/Unity.app/Contents/MacOS/Unity
On 64-bit Windows, type the following into the Command Prompt to launch Unity:
C:\Program Files\Unity\Editor\Unity.exe
On 32-bit Windows, type the following into the Command Prompt to launch Unity:
C:\Program Files (x86)\Unity\Editor\Unity.exe
Use the same method to launch standalone Unity games.
On macOS, type the following into the Terminal to silently launch Unity:
/Applications/Unity/Unity.app/Contents/MacOS/Unity -quit -batchmode -serial SB-XXXX-XXXX-XXXX-XXXX-XXXX -username 'JoeBloggs@example.com' -password 'MyPassw0rd'
Note: When activating via the command line using continuous integration (CI) tools like Jenkins, add the -nographics flag to prevent a WindowServer error.
On 64-bit Windows, type the following into the Command Prompt to silently launch Unity:
"C:\Program Files\Unity\Editor\Unity.exe" -quit -batchmode -serial SB-XXXX-XXXX-XXXX-XXXX-XXXX -username "JoeBloggs@example.com" -password "MyPassw0rd"
On 32-bit Windows, type the following into the Command Prompt to silently launch Unity:
"C:\Program Files (x86)\Unity\Editor\Unity.exe" -quit -batchmode -serial SB-XXXX-XXXX-XXXX-XXXX-XXXX -username "JoeBloggs@example.com" -password "MyPassw0rd"
As mentioned above, the Editor and built Unity games can be supplied with additional commands and information on startup. This section describes the command line options available.
| Command | Details |
|---|---|
| -assetServerUpdate <IP[:port] projectName username password [r <revision>]> | Force an update of the project in the Asset Server given by IP:port. The port is optional, and if not given it is assumed to be the standard one (10733). It is advisable to use this command in conjunction with the -projectPath argument to ensure you are working with the correct project. If no project name is given, then the last project opened by Unity is used. If no project exists at the path given by -projectPath, then one is created automatically. |
| -batchmode | Run Unity in batch mode. This should always be used in conjunction with the other command line arguments, because it ensures no pop-up windows appear and eliminates the need for any human intervention. When an exception occurs during execution of the script code, the Asset server updates fail, or other operations that fail, Unity immediately exits with return code 1. Note that in batch mode, Unity sends a minimal version of its log output to the console. However, the Log Files still contain the full log information. Opening a project in batch mode while the Editor has the same project open is not supported; only a single instance of Unity can run at a time. |
| -buildLinux32Player <pathname> | Build a 32-bit standalone Linux player (for example, -buildLinux32Player path/to/your/build). |
| -buildLinux64Player <pathname> | Build a 64-bit standalone Linux player (for example, -buildLinux64Player path/to/your/build). |
| -buildLinuxUniversalPlayer <pathname> | Build a combined 32-bit and 64-bit standalone Linux player (for example, -buildLinuxUniversalPlayer path/to/your/build). |
| -buildOSXPlayer <pathname> | Build a 32-bit standalone Mac OSX player (for example, -buildOSXPlayer path/to/your/build.app). |
| -buildOSX64Player <pathname> | Build a 64-bit standalone Mac OSX player (for example, -buildOSX64Player path/to/your/build.app). |
| -buildOSXUniversalPlayer <pathname> | Build a combined 32-bit and 64-bit standalone Mac OSX player (for example, -buildOSXUniversalPlayer path/to/your/build.app). |
| -buildTarget <name> | Allows the selection of an active build target before a project is loaded. Possible options are: standalone, Win, Win64, OSXIntel, OSXUniversal, OSXIntel64, Linux, Linux64, LinuxUniversal, iOS, Android, Web, WebStreamed, WebGL, XboxOne, PS4, PSP2, WindowsStoreApps, Tizen, Switch, WiiU, N3DS, tvOS, PSM, SamsungTV. |
| -buildWindowsPlayer <pathname> | Build a 32-bit standalone Windows player (for example, -buildWindowsPlayer path/to/your/build.exe). |
| -buildWindows64Player <pathname> | Build a 64-bit standalone Windows player (for example, -buildWindows64Player path/to/your/build.exe). |
| -stackTraceLogType | Detailed debugging feature. StackTraceLogging allows features to be controlled to allow detailed logging. All settings allow None, Script Only and Full to be selected. (for example, -stackTraceLogType Full) |
| -createProject <pathname> | Create an empty project at the given path. |
| -editorTestsCategories | Filter editor tests by categories. Separate test categories with a comma. |
| -editorTestsFilter | Filter editor tests by names. Separate test names with a comma. |
| -editorTestsResultFile | Path where the result file should be placed. If the path is a folder, a default file name is used. If not specified, the results are placed in the project’s root folder. |
| -executeMethod <ClassName.MethodName> | Execute the static method as soon as Unity is started, the project is open and after the optional Asset server update has been performed. This can be used to do tasks such as continous integration, performing Unit Tests, making builds or preparing data. To return an error from the command line process, either throw an exception which causes Unity to exit with return code 1, or call EditorApplication.Exit with a non-zero return code. To pass parameters, add them to the command line and retrieve them inside the function using System.Environment.GetCommandLineArgs. To use -executeMethod, you need to place the enclosing script in an Editor folder. The method to be executed must be defined as static. |
| -exportPackage <exportAssetPath1 exportAssetPath2 ExportAssetPath3 exportFileName> | Export a package, given a path (or set of given paths). In this example exportAssetPath is a folder (relative to to the Unity project root) to export from the Unity project, and exportFileName is the package name. Currently, this option only exports whole folders at a time. This command normally needs to be used with the -projectPath argument. |
| -force-d3d9 (Windows only) | Make the Editor use Direct3D 9 for rendering. Normally the graphics API depends on player settings (typically defaults to D3D11). |
| -force-d3d11 (Windows only) | Make the Editor use Direct3D 11 for rendering. Normally the graphics API depends on player settings (typically defaults to D3D11). |
| -force-glcore | Make the Editor use OpenGL 3/4 core profile for rendering. The Editor tries to use the best OpenGL version available and all OpenGL extensions exposed by the OpenGL drivers. If the platform isn’t supported, Direct3D is used. |
| -force-glcoreXY | Similar to -force-glcore, but requests a specific OpenGL context version. Accepted values for XY: 32, 33, 40, 41, 42, 43, 44 or 45. |
| -force-gles (Windows only) | Make the Editor use OpenGL for Embedded Systems for rendering. The Editor tries to use the best OpenGL ES version available, and all OpenGL ES extensions exposed by the OpenGL drivers. |
| -force-glesXY (Windows only) | Similar to -force-gles, but requests a specific OpenGL ES context version. Accepted values for XY: 30, 31 or 32. |
| -force-clamped | Used with -force-glcoreXY to prevent checking for additional OpenGL extensions, allowing it to run between platforms with the same code paths. |
| -force-free | Make the Editor run as if there is a free Unity license on the machine, even if a Unity Pro license is installed. |
| -importPackage <pathname> | Import the given package. No import dialog is shown. |
| -logFile <pathname> | Specify where the Editor or Windows/Linux/OSX standalone log file are written. |
| -nographics | When running in batch mode, do not initialize the graphics device at all. This makes it possible to run your automated workflows on machines that don’t even have a GPU (automated workflows only work when you have a window in focus, otherwise you can’t send simulated input commands). Please note that -nographics does not allow you to bake GI, since Enlighten requires GPU acceleration. |
| -password <password> | The password of the user, required when launching. |
| -projectPath <pathname> | Open the project at the given path. |
| -quit | Quit the Unity Editor after other commands have finished executing. Note that this can cause error messages to be hidden (however, they still appear in the Editor.log file). |
| -returnlicense | Return the currently active license to the license server. Please allow a few seconds before the license file is removed, because Unity needs to communicate with the license server. |
| -runEditorTests | Run Editor tests from the project. This argument requires the projectPath, and it’s good practice to run it with batchmode argument. quit is not required, because the Editor automatically closes down after the run is finished. |
| -serial <serial> | Activate Unity with the specified serial key. It is good practice to pass the -batchmode and -quit arguments as well, in order to quit Unity when done, if using this for automated activation of Unity. Please allow a few seconds before the license file is created, because Unity needs to communicate with the license server. Make sure that license file folder exists, and has appropriate permissions before running Unity with this argument. If activation fails, see the Editor.log for info. |
| -silent-crashes | Don’t display a crash dialog. |
| -username <username> | Enter a username into the log-in form during activation of the Unity Editor. |
| -password <password> | Enter a password into the log-in form during activation of the Unity Editor. |
| -disable-assembly-updater <assembly1 assembly2> | Specify a space-separated list of assembly names as parameters for Unity to ignore on automatic updates. The space-separated list of assembly names is optional: Pass the command line options without any assembly names to ignore all assemblies, as in example 1. Example 1 unity.exe -disable-assembly-updaterExample 2 has two assembly names, one with a pathname. Example 2 ignores A1.dll, no matter what folder it is stored in, and ignores A2.dll only if it is stored under subfolder folder:Example 2 unity.exe -disable-assembly-updater A1.dll subfolder/A2.dllIf you list an assembly in the -disable-assembly-updater command line parameter (or if you don’t specify assemblies), Unity logs the following message to Editor.log: [Assembly Updater] warning: Ignoring assembly [assembly_path] as requested by command line parameter.”). Use this to avoid unnecessary API Updater overheads when importing assemblies. It is useful for importing assemblies which access a Unity API when you know the Unity API doesn’t need updating. It is also useful when importing assemblies which do not access Unity APIs at all (for example, if you have built your game source code, or some of it, outside of Unity, and you want to import the resulting assemblies into your Unity project). Note: If you disable the update of any assembly that does need updating, you may get errors at compile time, run time, or both, that are hard to track. |
| -accept-apiupdate | Use this command line option to specify that APIUpdater should run when Unity is launched in batch mode. Example: unity.exe -accept-apiupdate -batchmode [other params]Omitting this command line argument when launching Unity in batch mode results in APIUpdater not running which can lead to compiler errors. Note that in versions prior to 2017.2 there’s no way to not run APIUpdater when Unity is launched in batch mode. |
using UnityEditor;
class MyEditorScript
{
static void PerformBuild ()
{
string[] scenes = { "Assets/MyScene.unity" };
BuildPipeline.BuildPlayer(scenes, ...);
}
}
static void PerformBuild ()
{
string[] scenes = { "Assets/MyScene.unity" };
BuildPipeline.BuildPlayer(scenes, ...);
}
The following command executes Unity in batch mode, executes the MyEditorScript.PerformBuild method, and then quits upon completion.
Windows:
C:\program files\Unity\Editor\Unity.exe -quit -batchmode -executeMethod MyEditorScript.PerformBuild
Mac OS:
/Applications/Unity/Unity.app/Contents/MacOS/Unity -quit -batchmode -executeMethod MyEditorScript.PerformBuild
The following command executes Unity in batch mode, and updates from the Asset server using the supplied project path. The method is executed after all Assets have been downloaded and imported from the Asset server. After the function has finished execution, Unity automatically quits.
/Applications/Unity/Unity.app/Contents/MacOS/Unity -batchmode -projectPath ~/UnityProjects/AutobuildProject -assetServerUpdate 192.168.1.1 MyGame AutobuildUser l33tpa33 -executeMethod MyEditorScript.PerformBuild -quit
These should only be used under special circumstances, or when directed by Unity Support.
| Command | Details |
|---|---|
| -enableIncompatibleAssetDowngrade | Use this when you have Assets made by a newer, incompatible version of Unity, that you want to downgrade to work with your current version of Unity. When enabled, Unity presents you with a dialog asking for confirmation of this downgrade if you attempt to open a project that would require it. Note: This procedure is unsupported and highly risky, and should only be used as a last resort. |
Standalone players built with Unity also understand some command line arguments:
| Command | Details |
|---|---|
| -adapter N (Windows only) | Allows the game to run full-screen on another display. The N maps to a Direct3D display adaptor. In most cases there is a one-to-one relationship between adapters and video cards. On cards that support multi-head (that is, they can drive multiple monitors from a single card) each “head” may be its own adapter. |
| -batchmode | Run the game in “headless” mode. The game does not display anything or accept user input. This is mostly useful for running servers for networked games. |
| -force-d3d9 (Windows only) | Force the game to use Direct3D 9 for rendering. Normally, the graphics API depends on player settings, and typically defaults to D3D11. |
| -force-d3d9-ref (Windows only) | Force the game to run using Direct3D’s “Reference” software renderer. The DirectX SDK has to be installed for this to work. This is mostly useful for building automated test suites, where you want to ensure rendering is exactly the same no matter what graphics card is being used. |
| -force-d3d11 (Windows only) | Force the game to use Direct3D 11 for rendering. |
| -force-d3d11-no-singlethreaded | Force DirectX 11.0 to be created without a D3D11_CREATE_DEVICE_SINGLETHREADED flag. |
| -force-glcore | Force the Editor to use OpenGL core profile for rendering. The Editor tries to use the best OpenGL version available, and all OpenGL extensions exposed by the OpenGL drivers. If the platform isn’t supported, Direct3D is used. |
| -force-glcoreXY | Similar to -force-glcore, but requests a specific OpenGL context version. Accepted values for XY: 32, 33, 40, 41, 42, 43, 44 or 45. |
| -force-clamped | Used together with -force-glcoreXY, this prevents checking for additional OpenGL extensions, allowing it to run between platforms with the same code paths. |
| -nographics | When running in batch mode, do not initialize graphics device at all. This makes it possible to run your automated workflows on machines that don’t even have a GPU. |
| -nolog (Linux & Windows only) | Do not produce an output log. Normally output_log.txt is written in the *_Data folder next to the game executable, where Debug.Log output is printed. |
| -popupwindow | Create the window as a a pop-up window, without a frame. |
| -screen-fullscreen | Override the default full-screen state. This must be 0 or 1. |
| -screen-height | Override the default screen height. This must be an integer from a supported resolution. |
| -screen-width | Override the default screen width. This must be an integer from a supported resolution. |
| -screen-quality | Override the default screen quality. Example usage would be: /path/to/myGame -screen-quality Beautiful
|
| -show-screen-selector | Forces the screen selector dialog to be shown. |
| -single-instance (Linux & Windows only) | Allow only one instance of the game to run at the time. If another instance is already running then launching it again with -single-instance focuses the existing one. |
| -parentHWND <HWND> delayed (Windows only) | Embed the Windows Standalone application into another application. When using this, you need to pass the parent application’s window handle (‘HWND’) to the Windows Standalone application. When passing -parentHWND 'HWND' delayed, the Unity application is hidden while it is running. You must also call SetParent from the Microsoft Developer library for Unity in the application. Microsoft’s SetParent embeds the Unity window. When it creates Unity processes, the Unity window respects the position and size provided as part of the Microsoft’s STARTUPINFO structure. To resize the Unity window, check its GWLP_USERDATA in Microsoft’s GetWindowLongPtr function. Its lowest bit is set to 1 when graphics have been initialized and it’s safe to resize. Its second lowest bit is set to 1 after the Unity splash screen has finished displaying.For more information, see this example: EmbeddedWindow.zip |
Universal Windows Apps don’t accept command line arguments by default, so to pass them you need to call a special function from MainPage.xaml.cs/cpp or MainPage.cs/cpp. For example:
appCallbacks.AddCommandLineArg("-nolog");
You should call this before the appCallbacks.Initialize() function.
| Command | Details |
|---|---|
| -nolog | Don’t produce UnityPlayer.log. |
| -force-driver-type-warp | Force the DirectX 11.0 driver type WARP device (see Microsoft’s documentation on Windows Advanced Rasterization Platform for more information). |
| -force-d3d11-no-singlethreaded | Force DirectX 11.0 to be created without a D3D11_CREATE_DEVICE_SINGLETHREADED flag. |
| -force-gfx-direct | Force single threaded rendering. |
| -force-feature-level–9–3 | Force DirectX 11.0 feature level 9.3. |
| -force-feature-level–10–0 | Force DirectX 11.0 feature level 10.0. |
| -force-feature-level–10–1 | Force DirectX 11.0 feature level 10.1. |
| -force-feature-level–11–0 | Force DirectX 11.0 feature level 11.0. |