OSExecute Method

Execute the file at the given path with the arguments passed as an array of strings. Platform path resolution will take place. The resolved file must exist and be executable.

The arguments are used in the given order and separated by a space, so OS.execute("ping", ["-w", "3", "godotengine.org"], false) will resolve to ping -w 3 godotengine.org in the system's shell.

This method has slightly different behavior based on whether the blocking mode is enabled.

If blocking is true, the Godot thread will pause its execution while waiting for the process to terminate. The shell output of the process will be written to the output array as a single string. When the process terminates, the Godot thread will resume execution.

If blocking is false, the Godot thread will continue while the new process runs. It is not possible to retrieve the shell output in non-blocking mode, so output will be empty.

The return value also depends on the blocking mode. When blocking, the method will return an exit code of the process. When non-blocking, the method returns a process ID, which you can use to monitor the process (and potentially terminate it with Kill(Int32)). If the process forking (non-blocking) or opening (blocking) fails, the method will return -1 or another exit code.

Example of blocking mode and retrieving the shell output:

var output = []
var exit_code = OS.execute("ls", ["-l", "/tmp"], true, output)

Example of non-blocking mode, running another instance of the project and storing its process ID:

var pid = OS.execute(OS.get_executable_path(), [], false)

If you wish to access a shell built-in or perform a composite command, a platform-specific shell can be invoked. For example:

OS.execute("CMD.exe", ["/C", "cd %TEMP% && dir"], true, output)

Note: This method is implemented on Android, iOS, Linux, macOS and Windows.